Migrating OnyxNet from WordPress to Astro and Cloudflare Pages

OnyxNet is my technical portfolio and the public documentation home for my network engineering and infrastructure work.

I previously hosted the site using WordPress. In October 2026, I migrated it to a static Astro website deployed through Cloudflare Pages, with the source maintained in GitHub.

Although this is a website project, its most relevant engineering work was in platform design, change management, delivery, DNS, troubleshooting, and operational verification. The site is also the publishing platform for my infrastructure case studies.

The Engineering Problem

The previous WordPress deployment provided a working website, but I wanted a platform that was better suited to version-controlled technical content.

My requirements had changed. I needed to publish engineering case studies, longer technical references, and architecture decisions without managing a traditional WordPress editing and plugin workflow for each change.

I also wanted to preserve a clear distinction between:

• onyxnet.live — professional infrastructure portfolio and technical documentation.
• onyxjeff.live — gaming, streaming, and creator content.

The migration needed to improve maintainability without turning the website itself into an unnecessarily complex application.

Requirements and Constraints

The new platform needed to:

1. Present a professional, responsive portfolio focused on network and infrastructure engineering.
2. Support reusable Markdown-based project case studies.
3. Provide searchable technical documentation and architecture decision records.
4. Use version control as the source of truth for website content and configuration.
5. Support repeatable builds and automatic deployment from GitHub.
6. Preserve the existing production domain and Cloudflare DNS management.
7. Keep the staging address out of search results while allowing the production site to be indexed.
8. Preserve a recovery path for the original WordPress website.

The implementation also needed to be inexpensive to operate, maintainable with my current tools, and straightforward to extend as new engineering work is documented.

Platform Selection

I selected a static-site architecture rather than recreating the old WordPress environment.

A static architecture is appropriate for this workload because the portfolio does not need a database or server-side application to render its public pages.

This decision reduces the number of application components I need to administer for the website. It does not eliminate the need for dependency updates, content validation, access control, and recovery planning.

Resulting Architecture

The publishing flow is:

Local development (VS Code + Astro)
                 |
                 v
        Local build / preview
                 |
                 v
          GitHub repository
                 |
                 v
    Cloudflare Pages build pipeline
                 |
                 v
     Static HTML, CSS, and assets
                 |
                 v
          https://onyxnet.live

Two content experiences share the same Astro build:

• The portfolio, Projects, Infrastructure, About, and Journal sections use shared Astro layouts and Markdown content.
• The Documentation section uses Starlight for structured technical reference material and Pagefind-backed search.

The Astro configuration uses https://onyxnet.live as the production site URL so generated canonical references and the sitemap use the intended domain.

The repository includes a .node-version file to record the Node.js version used for the build environment.

Implementation

Reusable case studies

I implemented an Astro content collection for engineering case studies. Each Markdown file carries structured metadata such as its title, description, category, status, technologies, and draft state.

A dynamic project route renders published studies using a common layout. This keeps the project pages visually consistent without copying an entire page template for each new project.

The same content collection also supplies selected projects on the homepage.

Technical documentation

Starlight provides a dedicated documentation structure for topics including networking, virtualization, storage, automation, monitoring, and architecture decisions.

An important distinction is that operational systems and proposed designs are documented separately. For example, an abandoned VLAN 700 proposal is recorded as an architecture decision rather than presented as deployed infrastructure.

The documentation search index is generated during the production build.

Git-based delivery

The working deployment process is:

1. Make and review a change locally.
2. Run the Astro development server to inspect the change.
3. Execute npm run build to generate the static site and search index.
4. Commit and push the change to GitHub.
5. Allow Cloudflare Pages to build and deploy the repository.
6. Validate representative URLs and behavior over HTTPS.

At the launch checkpoint, the production build successfully generated 21 static pages, and Pagefind indexed 21 HTML files. These are build counts, not performance measurements.

Domain migration and rollback planning

The new site was initially validated at onyxnet-website.pages.dev while the original WordPress site continued serving the custom domain.

Before retiring WordPress as the active website, I archived both its installation files and SQL database.

I then connected onyxnet.live to the Cloudflare Pages deployment. The original hosting backup was retained separately rather than committed to the public repository.

Troubleshooting: WWW Requests Failed

After the root domain was serving the new site, requests to www.onyxnet.live produced a Cloudflare 522 error.

The WWW hostname had a proxied CNAME record, but DNS resolution alone did not establish the desired application routing and redirect behavior.

Rather than modifying the working root-domain deployment, I configured a Cloudflare Redirect Rule to redirect WWW traffic to the apex domain.

The rule uses a wildcard match, preserves the requested path and query string, and returns HTTP 301.

I tested the behavior with PowerShell and curl.exe:

www.onyxnet.live/
    -> 301 -> onyxnet.live/

www.onyxnet.live/docs/network/vlans/?source=test
    -> 301 -> onyxnet.live/docs/network/vlans/?source=test

This corrected the observed failure for the tested requests without requiring a website rebuild or changes to the working apex route.

Search Indexing and Metadata

The staging deployment and production domain intentionally use different indexing behavior.

Cloudflare Pages applies an X-Robots-Tag: noindex response header to the pages.dev hostname through the repository’s public/_headers configuration.

The production hostname does not have that header. Its homepage HTML also has no noindex robots meta directive in the inspected markup.

The main Astro layout provides canonical URLs, descriptions, favicons, and Open Graph metadata. Starlight uses its own metadata system, so I added its social-sharing image through the Starlight configuration.

After the domain migration, the canonical homepage URL and social preview image reference the production hostname.

These checks establish that the tested pages are configured for discovery; they do not guarantee search engine indexing or ranking.

Verification and Results

The launch checks produced the following observable results.

I also tested navigation using desktop and mobile browser emulation.

These were targeted build, HTTP, and manual interface checks. They are not a full automated test suite, accessibility certification, security assessment, or performance benchmark. I have not published Lighthouse scores or claimed measured speed improvements.

Lessons Learned

A website migration is also an infrastructure change

The code can work while DNS, redirects, metadata, or indexing configuration still produces an incorrect user experience. Production validation must cover the entire request path.

Separate deployment from discovery

The staging hostname is useful for testing, but publishing it to a public URL does not mean it should be discoverable by search engines. Host-specific indexing controls preserve that distinction.

Validate the behavior, not just the configuration

The WWW redirect was not considered complete until HTTP response codes, path preservation, and query-string preservation were observed.

Preserve the rollback path

An archived application and database are valuable even when there is no expectation of returning to the previous platform. They preserve access to historical content and configuration.

Documentation is part of the deliverable

Publishing the design decisions, trade-offs, constraints, and verified outcomes makes the project more useful than a gallery of website screenshots.

Ownership and Next Steps

I developed the site iteratively with AI-assisted planning and drafting support, then used local builds, Git version control, Cloudflare configuration, and direct production checks to review and validate the resulting implementation.

The website is operational and has moved from migration work into normal maintenance and content development.

Planned improvements include adding sanitized architecture diagrams, real project evidence, deeper case studies, and ongoing documentation updates. No unsupported uptime, load-time, or reliability metrics are claimed.

Source and Live Deployment

• OnyxNet production website
• Website source repository
• Engineering projects
• Technical documentation