Migrating From WordPress to Astro  🔗 **Source:** [Migrating From WordPress to Astro](https://www.billerickson.net/migrating-from-wordpress-to-astro/) > [!note]+ Document Notes > --- > tags: [wordpress, static-site-generators, astro, headless-cms, web-performance, site-migration] > author: Bill Erickson > source: billerickson.net > reference: https://www.billerickson.net/migrating-from-wordpress-to-astro/ > date created: 2026-06-20 12:00 > --- > # 🏷️ Title: Migrating from WordPress to Astro > ## 🧭 Table of Contents > - [📝 Summary](#-summary) > - [📖 Main Content](#-main-content) > - [🗒️ Notes](#️-notes) > - [📚 References](#-references) > - [🗣️ Paraphrase](#️-paraphrase) > - [📰 Newsletter](#-newsletter) > - [✅ Action Items](#-action-items) > - [🧪 Hypotheses](#-hypotheses) > - [📊 Methodology](#-methodology) > - [❓ Questions](#-questions) > - [🔮 Future Research](#-future-research) > - [💡 Implications](#-implications) > - [🧠 Learning Styles Assessment](#-learning-styles-assessment) > - [📊 Accessibility Assessment](#-accessibility-assessment) > - [🌍 DEIB Assessment](#-deib-assessment) > - [✅ Logical Validity](#-logical-validity) > - [🛡️ DARVO Analysis](#-darvo-analysis) > - [🎯 Conclusion](#-conclusion) > ### 🔗 References > - [CultivateWP](https://cultivatewp.com) (Bill Erickson's WordPress agency) > - [Astro](https://astro.build) (static site generator / web framework) > - [Cloudflare Pages / Workers / Email Service](https://www.cloudflare.com) (hosting + serverless backend) > - [Joost de Valk — Astro SEO: the definitive guide](https://joost.blog) (centralized SEO reference Erickson cites) > ## 📝 Summary > - **What happened.** Bill Erickson — a 20-year WordPress developer and co-founder of the WordPress agency CultivateWP — documents migrating a nine-year-old WordPress client site (Sundheim Group) off WordPress entirely and onto a static **Astro** build hosted free on **Cloudflare**. An AI agent ("Hermes") did the first pass — content inventory, design brief, component rebuild — and Erickson did the higher-value cleanup, QA, and re-implementation of plugin-dependent features. > - **Why it matters.** A prominent, long-tenured WordPress developer publicly recommending *against* WordPress for a whole class of sites (small-business / brochure) is a meaningful signal about where WordPress's editorial-workflow value actually lives. It reframes WordPress not as a default but as one tool whose CMS overhead is only worth paying when an editorial workflow is genuinely needed. > - **Key stakeholders.** WordPress agencies and freelancers serving small-business clients; static-site/Jamstack tooling (Astro, Cloudflare); clients weighing maintenance cost vs. self-service editing; the broader "WP → headless/static" conversation; Courtney's own courtneyr.dev decisions. > - **Risks and tradeoffs.** The core tradeoff is **editing convenience**: Astro moves content into Git/Markdown/code-review/deploy, losing the browser admin UI non-technical users rely on. For active publishers with editorial workflows, custom fields, roles, previews, revisions, and plugin habits, dropping the CMS is "usually a non-starter." AI-assisted first passes leave broken functionality as dead static markup — QA is mandatory, not optional. > - **Bottom line.** Decide up front: WordPress when the site needs an editorial workflow; Astro when the site is mostly static, content fits Markdown, and the owner values speed, security, low maintenance, and simple infrastructure over browser-based editing. Communicate the pros and cons and let the client choose. > ## 📖 Main Content > - **The thesis (stated against interest).** "WordPress is not always the right solution for a website" — a strange sentence for a 20-year WordPress developer to write. Erickson still recommends WordPress for many publishers, including his CultivateWP clients, but no longer reaches for it automatically. For many small-business and brochure sites, Astro is now a better fit: a site that once needed a CMS, custom fields, plugins, and an admin workflow can become a simple static site with Markdown content and developer- or AI-assisted updates. > - **The case study.** Sundheim Group: built in 2017, only minimal changes since (sent as Word docs). The owner's active writing/podcast work had moved to Substack, so WordPress had become just "the front door" — services, case studies, credibility, contact. Keeping WordPress live meant managed hosting, plugin updates, backups, security patches, and a rarely-used admin backend. Astro kept the public site while removing the ongoing CMS burden, hosted free on Cloudflare. > - **When Astro fits.** When the public site is mostly static and the editing workflow does not need to live in a CMS — which "describes a lot of business websites." WordPress is often used as a database for simple pages that change a few times a year. > - **Step 1 — Inventory, not design.** Before rebuilding, catalog exactly what exists: public URLs, content types, taxonomies, redirects, embedded forms/scripts, images/files, one-off templates, SEO metadata. WordPress SEO plugin sitemaps are useful here (posts, pages, CPTs, taxonomies, last-modified dates). This became a `Migration Inventory.md` file giving the agent a concrete migration target. > - **Step 2 — Design brief.** Goal was to preserve, not redesign — the old site had an established professional identity. A `DESIGN.md` file captured typography, color palette, page structure, spacing, components, and guardrails. With inventory + brief in place, the agent had enough context to build the first Astro version. > - **Step 3 — Don't skip QA.** The AI's first pass moved visible content over but left broken functionality as static markup. The cleanup pass caught the details: contact page needed a real replacement form; newsletter page needed a working Substack signup instead of stale Gravity Forms markup; assessment/speaking pages had third-party embeds to preserve deliberately; a video page's old YouTube shortcode had to become a responsive HTTPS iframe. > - **The contact form (the one technical fix detailed).** Extracted into a reusable Astro component; submissions post to a Cloudflare Worker that verifies a Turnstile captcha server-side, normalizes fields, and sends notification via Cloudflare's Email Service `send_email` binding — no SMTP or paid transactional email needed, using a verified Cloudflare Email Routing destination address. > - **SEO still matters.** A static site is "a clean slate, which is both helpful and dangerous." Centralize SEO (per Joost de Valk's Astro SEO guide) rather than hand-rolling tags per page: shared layout-level SEO layer, canonical URLs from configured production URL, robots handling that can noindex staging, `@astrojs/sitemap`, RSS feeds, JSON-LD structured data, and build-time checks for metadata length, H1s, alt text, and internal links. "SEO should be part of the site system, not something you remember to paste into individual pages." > - **PageSpeed improves, but not automatically.** Astro starts ahead (static HTML, minimal JS, CDN assets), but gains still require the boring work. Sundheim's old WordPress site scored **35** mobile in PageSpeed Insights; the initial Astro build hit ~**85**; Erickson reached **100** across Performance, Accessibility, Best Practices, and SEO by optimizing images (lighter WebP, responsive variants), removing unnecessary JS, making embedded video responsive, and replacing custom fonts with a modern font stack (the client later reversed the font change). > - **Why AI agents excel at Astro optimization.** Lighthouse gives a tight feedback loop and the agent controls the entire stack — run audit, find bottleneck, make a focused change, re-test. Much harder on WordPress, where a plugin or script added after launch can wipe out hand-tuned gains. > - **The real tradeoff — editing.** WordPress gives non-technical users an admin UI; Astro gives a simpler/faster/safer public site but pushes content changes into Git, Markdown, code review, and deployment. For clients making minor changes a few times a year, emailing the developer can be easier than logging in, and hosting/plugin savings can exceed the cost of occasional dev updates. **Not universal:** for active publishers the lack of a full CMS is "usually a non-starter." > - **Current approach.** Recommend WordPress when an editorial workflow is needed (most CultivateWP clients); recommend Astro when the site is mostly st WordPress is not always the right solution for a website. That is a strange sentence for me to write. I have spent **20 years** building with WordPress, and I still think it is the right tool for many publishers, including my clients at [CultivateWP](https://cultivatewp.com/). In the past, I used WordPress for everything: blogs, business sites, [internal CRMs](https://www.billerickson.net/twentyten-crm/), and even a [rebuild of my favorite bookmarking site](https://github.com/billerickson/be-delicious). But I no longer reach for WordPress automatically. For many small business and brochure sites, Astro is now a better fit. A site that once needed a CMS, custom fields, plugins, and an admin workflow can often become a simple static site with Markdown content and developer-assisted, or AI-assisted, updates. I recently rebuilt the [Sundheim Group](https://sundheim.group/) site by moving a nine-year-old WordPress site to a static Astro build hosted on Cloudflare.  [My Hermes agent](https://hermes-agent.nousresearch.com/) did the first pass: creating an inventory of the old site’s content, creating a design brief from the existing WordPress site, and rebuilding the content with Astro components. The important work came next: reviewing what transferred well, fixing what did not, and rebuilding the pieces that WordPress plugins used to handle. #### When Astro is a good fit Astro is a good fit when the public site is mostly static and the editing workflow does not need to happen in a CMS. That describes a lot of business websites. WordPress is often being used as a database for simple pages that only change a few times a year. The Sundheim Group site was a good example. We built the original site in 2017. Since then, only minimal content changes had been made, and they were done by sending me Word docs. Doug’s active writing and podcast work had moved to Substack. The WordPress site had become the front door: services, case studies, credibility, and contact. Keeping WordPress live meant managed hosting, plugin updates, backups, security patches, and an admin backend that was rarely used. Astro let us keep the public website and remove the ongoing CMS burden. The new site is hosted for free on Cloudflare. #### Start with an inventory The first step is not design. It is inventory. Before rebuilding anything, I wanted to know exactly what existed on the old site: * public URLs * content types * taxonomies * redirects * embedded forms and scripts * images and files * one-off templates * SEO metadata WordPress SEO plugin sitemaps are useful for this. They list posts, pages, custom post types, taxonomies, and last modified dates. I turned that into a `Migration Inventory.md` file that described the site structure and gave the agent a concrete migration target. #### Create the design brief The goal was not to redesign Sundheim Group from scratch. The old site already had an established, professional visual identity. The rebuild needed to preserve that feel while replacing the implementation with cleaner, reusable pieces. I created a [DESIGN.md file](https://github.com/google-labs-code/design.md) from the existing website. It described the typography, color palette, page structure, spacing, components, and design guardrails. Once the content inventory and design brief were in place, the agent had enough context to build the first Astro version. #### Don’t skip the QA process You can copy the obvious pages and still miss the behavior hiding in the content. Old WordPress sites often contain newsletter embeds, Gravity Forms, survey scripts, YouTube shortcodes, tracking snippets, unexpected image paths, redirects, and one-off page templates. On this project, the first Astro pass moved the visible content over but left broken functionality as static markup in the page. The cleanup pass found the important details: * The contact page needed a real replacement form. * The newsletter page needed a working Substack signup form instead of stale Gravity Forms markup. * The assessment and speaking pages had third-party embeds that needed to be preserved deliberately. * A video page had an old YouTube shortcode that needed to become a responsive HTTPS iframe. I extracted the contact form into a reusable Astro component. Submissions post to a Cloudflare Worker, which verifies a Turnstile captcha server-side, normalizes the fields, and sends the notification through Cloudflare’s Email Service `send_email` binding. The form does not need SMTP or a paid transactional email service. It uses a verified Cloudflare Email Routing destination address. In Cloudflare, [destination addresses](https://developers.cloudflare.com/email-service/configuration/email-routing-addresses/#destination-addresses) are account-level verified recipients. The same verified address can receive direct sends from a Worker. For the newsletter page, I inspected the live Substack form and rebuilt a simple static form that posts to Substack’s real endpoint. For the assessment page, I kept the SurveyGizmo script because that page’s purpose was the external assessment. The difference is that it now lives in a route-specific component instead of being buried inside a large escaped content blob. #### SEO still matters Astro gives you a clean slate, which is both helpful and dangerous. A static site can be very SEO-friendly, but not if every page hand-rolls its own title tag, canonical URL, Open Graph tags, and schema. Joost’s [Astro SEO: the definitive guide](https://joost.blog/astro-seo-complete-guide/) really helped me with this. He recommends centralizing SEO instead of sprinkling tags throughout the site. On these Astro builds, that means: * a shared layout-level SEO layer * canonical URLs generated from the configured production site URL * robots handling that can noindex staging while allowing production indexing * `@astrojs/sitemap` for sitemap output * RSS feeds for blog or article content * JSON-LD structured data for the site, person or organization, pages, breadcrumbs, and blog surfaces * build-time checks for metadata length, H1s, image alt text, and internal links where possible SEO should be part of the site system, not something you remember to paste into individual pages. #### PageSpeed improves, but not automatically Astro starts with a big advantage: static HTML, minimal JavaScript, and assets that can be served from a CDN. That does not mean there’s no room for improvement. On Sundheim Group, the old WordPress site scored 35 for mobile performance in PageSpeed Insights. After the initial Astro build, the score was around 85. I eventually reached 100 across Performance, Accessibility, Best Practices, and SEO by fixing the boring details: * optimizing images and generating lighter WebP versions * adding responsive image variants for large hero images * removing unnecessary JavaScript from pages that did not need it * making embedded video responsive instead of layout-breaking * replacing custom fonts with a [modern font stack](https://modernfontstacks.com/) (although the client pushed back and had me reverse this one) Astro makes a fast site easier to build, but PageSpeed still rewards the same practical work: image sizes, font loading, layout stability, and delay/defer scripts. AI agents are great at optimizing Astro sites because Lighthouse gives them a tight feedback loop and they are in control of the entire stack. They can run the audit, identify the next bottleneck, make a focused change, and test again. That is much harder on WordPress. I can hyper-optimize a WordPress theme, but a plugin or script added after launch can wipe out those gains. #### The tradeoff is editing The tradeoff is editing convenience. WordPress gives non-technical users an admin UI. Astro gives you a simpler, faster, safer public site, but content changes usually move into Git, Markdown, code review, and deployment. For many business clients, that is not a problem. If they only make minor content changes a few times a year, emailing me directly can be easier than logging into WordPress. The cost savings on hosting and plugins can also exceed the cost of having me make those occasional updates. But this is not a universal recommendation. For active publishers, the lack of a full CMS is usually a non-starter. Their editorial workflow is built around WordPress, custom fields, roles, previews, revisions, recipe plugins, and team habits. An Astro-based CMS may be interesting, but it will not replace that workflow for most of them. #### My current approach I still recommend WordPress when the site needs an editorial workflow, like most of my clients at [CultivateWP](https://cultivatewp.com). I recommend Astro when the site is mostly static, the content can live in Markdown, and the owner values speed, security, low maintenance, and simple infrastructure more than a browser-based editing experience. The key is to decide that up front. You should clearly communicate the pros and cons to the client, and let them make the decision., Migrating From WordPress to Astro, billerickson.net, 01kvkr26vqr2jm6jwq3zspr5ce.