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 > <!-- deep-read:sections start --> ## 🧭 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 static, content can live in Markdown, and the owner values speed/security/low-maintenance/simple infrastructure over browser editing. Decide up front, communicate pros and cons, let the client decide. ### 🗒️ Notes - **Stated against interest.** The framing's power is that a 20-year WordPress veteran and agency owner is the one saying WordPress is over-applied — this is a credibility signal, not a competitor's attack. - **The "front door" pattern.** WordPress decaying into a low-change brochure site while real publishing migrates to Substack is the exact trigger condition. The CMS outlived its workflow. - **Maintenance burden is the hidden cost.** Managed hosting + plugin updates + backups + security patches + a rarely-used admin backend — all carrying cost for a site that changes a few times a year. - **Inventory before design** is the methodological core: enumerate URLs, content types, taxonomies, redirects, embedded forms/scripts, images, one-off templates, SEO metadata. SEO-plugin sitemaps seed this. Output is a Markdown file (`Migration Inventory.md`) as the agent's migration target. - **AI agent ("Hermes") did the first pass**; the human did the load-bearing work — review what transferred, fix what didn't, rebuild plugin-handled pieces. The article is as much about agent-assisted migration *discipline* as about Astro. - **Silent-failure trap:** the AI moved visible content but left broken functionality as static markup — forms and embeds *looked* present but were dead. QA is the irreplaceable step. - **Plugin replacements:** Gravity Forms → Cloudflare Worker contact form (Turnstile + Email Service); Gravity Forms newsletter → static form posting to Substack's real endpoint; SurveyGizmo script preserved but moved into a route-specific component; YouTube shortcode → responsive HTTPS iframe. - **Cloudflare-native backend:** Worker + Turnstile + `send_email` binding + verified Email Routing destination = no SMTP, no paid transactional email service. - **Performance receipts:** 35 → ~85 → 100. Astro is a head start, not a free win; image sizes, font loading, layout stability, and deferred scripts still matter. - **Agent + Lighthouse = tight loop:** full-stack control lets the agent audit→fix→retest. WordPress's plugin layer breaks that loop because post-launch additions can erase gains. - **The tradeoff is editing**, full stop. Git/Markdown/review/deploy vs. admin UI. The decision is a client-fit question, not a tech-superiority claim. - **Connects to WP → headless/static theme** and to Courtney's courtneyr.dev: the same "is the CMS workflow actually being used?" audit applies. ## 📚 References - [Bill Erickson — Migrating from WordPress to Astro](https://www.billerickson.net/migrating-from-wordpress-to-astro/) (this article) - [CultivateWP](https://cultivatewp.com) — Erickson's WordPress agency (where he still recommends WordPress) - [Astro](https://astro.build) — the static-site framework used for the rebuild - [Cloudflare](https://www.cloudflare.com) — Pages hosting, Workers, Turnstile, Email Routing / Email Service `send_email` binding - [Joost de Valk — Astro SEO: the definitive guide](https://joost.blog) — the centralized-SEO reference Erickson credits - [Substack](https://substack.com) — where the client's active writing/podcast work moved (newsletter signup endpoint) ## 🗣️ Paraphrase - A 20-year WordPress developer and agency co-founder argues WordPress isn't always the right tool; for many small-business and brochure sites, a static Astro build is now a better fit than a CMS with custom fields, plugins, and an admin workflow. - He rebuilt a nine-year-old WordPress client site (Sundheim Group) as a static Astro site hosted free on Cloudflare, using an AI agent for the first pass and his own hands for the cleanup. - Astro fits when the public site is mostly static and editing doesn't need a CMS — which describes many business sites being used as a database for pages that change a few times a year. - Migration starts with inventory, not design: catalog URLs, content types, taxonomies, redirects, embeds, images, templates, and SEO metadata into a Markdown brief for the agent. - A design brief preserves the existing visual identity rather than redesigning; together inventory + brief give the agent enough context for a first build. - QA is non-negotiable: the AI's first pass left broken forms and embeds as dead static markup that had to be rebuilt (Cloudflare Worker contact form, static Substack signup, preserved third-party embeds, responsive video iframe). - SEO must be centralized at the layout level — canonical URLs, sitemap, RSS, JSON-LD, robots handling, build-time checks — not pasted per page. - Astro is a performance head start, not an automatic win; the score went 35 → ~85 → 100 only after the boring image/font/JS/layout work. - The real tradeoff is editing convenience: Astro moves content into Git/Markdown/review/deploy, which suits infrequently-edited business sites but is a non-starter for active publishers with editorial workflows. Decide up front and let the client choose. ## 📰 Newsletter **A WordPress veteran moves a client off WordPress — on purpose** When someone who's built with WordPress for 20 years and co-founded a WordPress agency writes "WordPress is not always the right solution," it's worth a read. Bill Erickson just documented migrating a nine-year-old client site (Sundheim Group) off WordPress and onto a static **Astro** build hosted *free* on Cloudflare — and his framing is refreshingly un-dramatic. The site had quietly become a "front door": services, case studies, contact, changed a few times a year via Word docs while the client's real writing moved to Substack. So why keep paying for managed hosting, plugin updates, backups, security patches, and an admin backend nobody logs into? The migration playbook is the useful part: **inventory before design** (a `Migration Inventory.md` of URLs, content types, redirects, embeds, SEO metadata), a `DESIGN.md` brief to *preserve* the look, an AI agent for the first pass — and then the human doing the load-bearing QA, because the agent happily leaves broken forms as dead static markup. He rebuilt the contact form as a Cloudflare Worker (Turnstile + Email Service, no SMTP), swapped stale Gravity Forms for a static Substack signup, and took PageSpeed from **35 → 100**. The honest catch: the tradeoff is *editing*. Astro means Git, Markdown, review, deploy — great for a brochure site, a non-starter for an active publisher with custom fields, roles, and revisions. His rule: decide up front, lay out the pros and cons, let the client choose. WordPress isn't losing — it's getting *scoped*. ## ✅ Action Items #### DevRel - Developer advocacy: turn "inventory before design + mandatory QA" into a talk/demo on disciplined AI-assisted migrations. - Education: workshop on rebuilding plugin-dependent features (forms, embeds) as serverless components when leaving WordPress. - Developer experience: publish a reference `Migration Inventory.md` + `DESIGN.md` template pair for agent-driven migrations. - Developer marketing: clip the "20-year WP dev recommends Astro" angle as honest, credible content. - Community management: host an agency-owner roundtable on "when NOT to use WordPress." - Internal/external/cross-project: share migration QA checklists (find dead static markup) across the ecosystem. #### OSPO - Policy & Governance: guidance on disclosing AI-agent involvement in client deliverables. - License Compliance: confirm provenance when an agent copies an existing site's design into new components. - Security Management: review server-side form handling patterns (Turnstile, Email Routing) as a safer default than plugin SMTP. - Software Inventory: catalog static-site/serverless stacks (Astro + Cloudflare Workers) as alternatives to plugin-heavy WordPress. - Developer Support: consultation hours on WordPress → Astro migration tradeoffs. - Community Engagement: fund a case study on maintenance-cost vs. editing-convenience for small-business sites. - Strategic Alignment: track "sites that don't need a CMS" as a scoping signal for the ecosystem. #### Community - Maintainers: Not directly applicable to this source. - Contributors: document the "headless/static exit" decision so newcomers understand WordPress's actual value boundary. - Sponsors: Not applicable to this source. - Ecosystem: coordinate shared migration tooling and QA patterns for WP → static moves. #### WordPress - Core: note the signal that low-change brochure sites carry CMS overhead they don't use — consider lighter-weight defaults. - Core Performance: publish realistic WordPress-vs-static PageSpeed baselines and how plugins erode hand-tuned gains. - Core AI: document patterns for AI-agent-assisted migration *into* and *out of* WordPress responsibly. - **Core Program Team:** coordinate a cross-team view on the "WordPress as over-applied default" critique. - Mobile: Not applicable to this source. - Playground: Playground could host migration-preview/diff demos — explore as a tooling fit. - Community: WordCamp session on "choosing WordPress vs. static — and saying no gracefully." - Training: learning path on serverless form/embed replacements for ex-WordPress sites. - Marketing: reframe the value story around editorial workflow, not "WordPress for everything." - Support: anticipate questions about decommissioning rarely-used WordPress installs safely. - Design: document "preserve, don't redesign" design-brief practice for migrations. - Documentation: examples-first guide to exporting WP content (inventory, redirects, metadata) cleanly. - Photos / TV / Openverse: Not applicable to this source. - Polyglots: glossary for "static site generator," "headless," "build-time," "serverless function." - Accessibility: note that the rebuild reached Lighthouse 100 Accessibility — capture the practices (see Accessibility Assessment). - Meta: Not applicable to this source. - CLI: WP-CLI is well-suited to content/redirect export for migrations — document robust patterns. - Hosting: managed-WP maintenance burden is the stated cost driver — publish honest "is WordPress worth it here?" guidance. - Tide / Themes / Plugins: note that plugin sprawl (forms, SEO, surveys) is exactly what the migration had to unwind. #### The WPCC - Programs: fellowship on sustainable, right-sized infrastructure choices for small agencies and clients. - Projects: documentation sprint on WP → static migration QA and serverless feature replacement. - Funding experiments: microgrants for open tooling that audits "does this site actually use its CMS?" ### FAIR - Technical independence: a static, Git-versioned site with serverless functions is a strong independence/portability story — document it. - Policies and covenants: transparency on AI-agent involvement and client decision-making in migrations. - Productized governance artifacts: a "WordPress vs. Astro" decision scorecard clients can sign off on. ## 🧪 Hypotheses - H1: For sites that change a few times a year, total cost of ownership (hosting + plugins + maintenance) is lower on static Astro/Cloudflare than on managed WordPress, even including occasional paid developer edits. - H2: AI-agent-assisted migrations leave a predictable class of silent failures (dead static markup where dynamic plugin features were), so a mandatory QA pass measurably reduces post-launch defects. - H3: Migrating a low-change WordPress brochure site to static Astro yields large PageSpeed gains (e.g., 35 → 100) primarily from reduced JS and asset optimization rather than from the framework alone. - H4: Sites where the owner's active publishing has moved off-platform (e.g., to Substack) are the highest-yield candidates for CMS removal. - H5: Centralizing SEO at the layout level reduces metadata defects (missing canonicals, duplicate titles) compared to per-page hand-rolled tags. - H6: For active publishers, removing the CMS reduces editorial throughput enough to outweigh maintenance savings (the non-starter boundary). ### 📊 Methodology - H1/H3: instrument a cohort of migrated sites — track hosting/plugin/maintenance spend and PageSpeed before/after, attributing gains to JS removal, image/WebP, fonts, layout stability vs. framework baseline. - H2: controlled migration study comparing agent-only output vs. agent+human-QA output, counting dead-markup/broken-feature defects at launch. - H4/H6: survey + cohort analysis correlating "active publishing moved off-platform" and "editorial-workflow dependence" against migration success and editing-throughput outcomes. - H5: audit metadata correctness (canonicals, titles, OG, schema) across layout-centralized vs. per-page Astro builds. ### ❓ Questions - At what edit frequency does the editing-convenience tradeoff flip back in WordPress's favor? - How do you safely decommission the old WordPress install (redirects, archives, email, DNS) without breaking SEO? - Does an "Astro-based CMS" ever close enough of the gap to win active publishers, or is that structurally a non-starter? - How repeatable is the agent-assisted playbook across sites with heavier plugin dependence (membership, e-commerce, custom post types)? ### 🔮 Future Research - Empirical TCO comparison: managed WordPress vs. static Astro/Cloudflare across edit-frequency bands. - A taxonomy of AI-migration silent failures and a QA checklist that catches each class. - Decision framework / scorecard predicting WordPress-vs-static fit from workflow, edit frequency, and plugin dependence. - Longevity study: do static-migrated sites actually incur fewer security/maintenance incidents over 3–5 years? ### 💡 Implications - **Practice:** Audit whether a site's CMS workflow is actually used before defaulting to WordPress; inventory before design; treat QA as the load-bearing step in any AI-assisted migration. - **Policy:** Disclose AI-agent involvement and design-provenance in client deliverables; get explicit client sign-off on the editing tradeoff. - **Security:** Static + serverless (Worker + Turnstile + verified Email Routing) shrinks the attack/maintenance surface vs. plugin-heavy WordPress, but moves trust to the platform. - **Education:** WordPress training should teach where the CMS's value boundary is, not just how to use it everywhere. - **Funding models:** Agencies may shift from recurring maintenance retainers toward occasional-edit + low-infrastructure arrangements, changing how small-site work is priced. ### 🧠 Learning Styles Assessment - Reading level estimate: clear technical prose, short declarative sentences; ~Flesch–Kincaid Grade 9–11 (developer vocabulary: "canonical URL," "JSON-LD," "send_email binding," "Turnstile"). Flesch Reading Ease ~50–60. #### 👀 Visual learners - Present: none — prose only; no diagrams or screenshots in the supplied text. - Improve: a before/after PageSpeed graphic (35 → 85 → 100); a migration-pipeline diagram (inventory → brief → agent build → QA); a decision tree for WordPress vs. Astro. #### 🔊 Aural learners - Present: none — text article, no audio. - Improve: a 3-minute audio summary; a podcast segment walking the migration steps. #### 🗣️ Verbal learners - Present: strong — vivid framing ("clean slate, which is both helpful and dangerous"), concrete plugin-to-serverless mappings, plain definitions in context. - Improve: a glossary callout (static site generator, headless, build-time checks, serverless function, binding). #### 🧩 Kinesthetic learners - Present: implicit step-by-step (inventory → brief → build → QA) and one configuration-level code description. - Improve: a hands-on lab — migrate a sample WordPress brochure page to Astro; a QA checklist to run against an agent's first pass. #### 🧠 Logical learners - Present: clear cause→effect (unused CMS → maintenance cost → remove it; agent first pass → silent failures → QA) and quantified outcomes. - Improve: a decision tree for fit; a TCO table comparing the two stacks. #### 🧑‍🤝‍🧑 Social learners - Present: client-collaboration framing ("communicate the pros and cons … let them make the decision"). - Improve: discussion prompts for agency peer groups on scoping conversations with clients. #### 🧘‍♀️ Solitary learners - Present: reflective practitioner narrative from one developer's experience. - Improve: journaling prompts ("which of my maintained sites don't actually use their CMS?"). #### 🌿 Naturalistic learners - Present: implicit sustainability angle — less compute, free static hosting, fewer always-on services. - Improve: tie static hosting + minimal JS to energy/compute footprint and long-term maintenance ecology. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: the article uses headings; the migrated site reportedly scored 100 on Lighthouse Accessibility. - Improve: confirm semantic landmarks and heading hierarchy on both the article page and the rebuilt site. #### Keyboard navigation - Present: standard content page; rebuilt contact form should be keyboard-operable. - Improve: verify form controls and any iframes/embeds have visible focus and logical tab order. #### Contrast and readability - Present: clean text layout; Lighthouse 100 suggests contrast was addressed on the rebuild. - Improve: verify 4.5:1 on links and form UI; re-check after the client's font reversal. #### Text resizing and reflow - Present: responsive content; responsive image/video work described. - Improve: confirm no clipping at 200% zoom, especially on the responsive video iframe. #### Media and captions - Present: the embedded YouTube video became a responsive HTTPS iframe. - Improve: ensure embedded video has captions and that the iframe has a descriptive title attribute. #### Forms and interactions - Present: contact form rebuilt with server-side Turnstile verification and field normalization. - Improve: ensure labels, accessible error handling/inline validation, and that the Turnstile challenge has an accessible fallback. #### Standards reference - Maps to WCAG 2.2 AA: 1.4.3 Contrast, 2.1.1 Keyboard, 1.4.10 Reflow, 1.2.2 Captions, 2.4.6 Headings/labels, 3.3.1/3.3.3 Error identification/suggestion, 4.1.2 Name/Role/Value (form + iframe title). ### 🌍 DEIB Assessment #### Cultural breadth - Present: limited — a single US-based developer's practitioner account; no cross-region or multilingual framing. - Improve: address how the Git/Markdown editing tradeoff affects non-technical and non-English-speaking site owners. #### Inclusive language - Present: plain, jargon-explained-in-context, no exclusionary terms. - Improve: define developer jargon inline (binding, canonical, JSON-LD) for non-technical client readers. #### Neurodiversity support - Present: strong — consistent structure, short sections, clear subheadings, predictable step order. - Improve: add a TL;DR decision box and chunked summaries at section heads. #### Representation - Present: single-author practitioner voice; one client example. - Improve: include the non-technical client's perspective on losing the admin UI, and varied site types beyond one brochure site. #### Psychological safety - Present: honest, non-dogmatic framing; acknowledges WordPress's strengths and the tradeoff; lets the client decide. - Improve: address the anxiety of clients/agencies whose value is tied to recurring CMS maintenance. ### ✅ Logical Validity #### Strong reasoning - Causal (unused CMS → cost → remove): well-mechanized — the site's low change frequency and off-platform publishing cleanly justify removing the maintenance burden. - Empirical (PageSpeed 35 → 85 → 100): concrete, measured outcomes attributed to specific work (images, fonts, JS, layout), not just the framework. - Conditional / scoped claim: the thesis is explicitly bounded ("not a universal recommendation"; active publishers = non-starter), which strengthens validity by stating its own limits. - Stated-against-interest credibility: a 20-year WordPress dev recommending Astro is hard to dismiss as motivated boosterism. #### Fallacies - **Hasty generalization (mild)** — "That describes a lot of business websites." Generalizes from one nine-year-old, off-platform-publishing client to "a lot of business websites" without data. Fix: present as a hypothesis with the qualifying conditions (low edit frequency, no editorial workflow) made explicit and ideally quantified. - **Survivorship / single-case bias** — the whole argument rests on one successful migration (Sundheim Group); migrations that went poorly or clients who regretted losing the admin UI aren't represented. Fix: report a portfolio of outcomes, including failures and client pushback (the font reversal hints at this). - **Appeal to (automation) authority — partial** — "AI agents are great at optimizing Astro sites." Stated as general fact from one agent's ("Hermes") good experience on a tight Lighthouse loop. Fix: bound to "well-scoped, measurable tasks with a feedback loop"; note the silent-failure failure mode the author himself documents. - **Suppressed cost (framing)** — hosting "free on Cloudflare" foregrounds savings while the recurring developer-edit cost and migration labor are mentioned but not tallied. Fix: present a like-for-like TCO including migration effort and per-edit developer time. #### Tone of voice - Reflective, candid, practitioner-practical; explicitly self-aware ("a strange sentence for me to write"). Balanced and non-evangelical — repeatedly credits WordPress's strengths and names the tradeoff. Mild advocacy for Astro is tempered by scoping and a client-decides ethic. ### 🛡️ DARVO Analysis - Deny: None — the author doesn't deny WordPress's value; he affirms it for editorial-workflow sites. - Attack: None — no accusers and no credibility-undermining; peers and WordPress itself are treated respectfully. - Reverse victim/offender: None. - Overall: DARVO is not applicable to this source. It's a measured, self-critical practitioner piece that states its own limits ("not a universal recommendation") rather than deflecting; there is no defensive reframing to analyze. ## 🎯 Conclusion - **Bottom line.** A veteran WordPress developer makes the un-tribal case that WordPress is over-applied: for mostly-static small-business sites whose owners edit a few times a year and whose real publishing has moved elsewhere, a static Astro build on free Cloudflare hosting removes real maintenance, security, and performance burden. The migration discipline — inventory before design, a preserve-don't-redesign brief, an AI agent for the first pass, and a mandatory human QA pass that rebuilds plugin features as serverless components — is the transferable part. The one hard tradeoff is editing convenience: no admin UI, content lives in Git/Markdown. Decide up front, communicate it, let the client choose. - **Next steps for readers.** (1) Audit your maintained sites: which actually use their CMS workflow vs. sit as low-change brochures? (2) For a candidate, build a `Migration Inventory.md` + `DESIGN.md` before touching design. (3) If using an AI agent, plan the QA pass first — hunt for dead static markup where dynamic features were. (4) Centralize SEO at the layout level and verify PageSpeed gains with the boring image/font/JS work. (5) For courtneyr.dev specifically, run the same "is the CMS workflow being used?" question before assuming WordPress is the default. ## 🔄 Refactor Appendix — Migrating from WordPress to Astro > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults applied. Resonance filter on. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### [H1] WordPress is not the automatic default for every site > [!quote] ID:rw_pending > "WordPress is not always the right solution for a website. That is a strange sentence for me to write." **Context & use**: - Said by a 20-year WordPress developer and CultivateWP co-founder — stated against interest. - Reframes WordPress as one tool whose value is the editorial workflow, not a universal default. **Tags**: #xref #aphorisms #share **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H2] Static Astro fits sites that don't need a CMS editing workflow > [!quote] ID:rw_pending > "Astro is a good fit when the public site is mostly static and the editing workflow does not need to happen in a CMS." **Context & use**: - Many business sites use WordPress as a database for pages that change a few times a year. - Removes managed hosting, plugin updates, backups, security patches, and an unused admin backend. **Tags**: #xref #articleseed **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H3] Start a migration with inventory, not design > [!quote] ID:rw_pending > "The first step is not design. It is inventory." **Context & use**: - Catalog URLs, content types, taxonomies, redirects, embeds, images, templates, SEO metadata into a `Migration Inventory.md`. - Gives an AI agent a concrete migration target before any rebuild. **Tags**: #xref #aphorisms **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H4] AI agents leave broken features as dead static markup > [!quote] ID:rw_pending > "the first Astro pass moved the visible content over but left broken functionality as static markup in the page." **Context & use**: - The QA cleanup pass is the load-bearing step: rebuild forms and embeds (Cloudflare Worker contact form, static Substack signup, preserved third-party scripts, responsive video iframe). - Silent-failure trap — features look present but are non-functional. **Tags**: #xref #addendum **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] A CMS is worth its overhead only when its editing workflow is actually used **Claim** (one sentence, Courtney's voice): The maintenance, security, and performance cost of running a CMS is justified only when the site's editorial workflow is genuinely in use, so the deciding question for WordPress-vs-static is how the site is edited, not what the site contains. **Evidence pointer**: [[#H2]] **Scope & conditions**: Holds for small-business/brochure sites with low edit frequency and no editorial workflow. Breaks for active publishers dependent on custom fields, roles, previews, revisions, and plugin habits, where removing the CMS is a non-starter. **Links**: - [[WordPress as editorial workflow]] — because extends - [[Static site generators]] — because contrasts on editing model - [[Total cost of ownership for small sites]] — because applies-in the maintenance-burden decision <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Audit courtneyr.dev and any maintained client sites: which actually use the CMS editing workflow vs. sit as low-change brochures? — https://www.billerickson.net/migrating-from-wordpress-to-astro/ #fleeting #inbox - [F2] Open question: at what edit frequency does the Git/Markdown editing tradeoff flip back in WordPress's favor? #fleeting #inbox ### → Things 3 (max 2 actions) - [ ] Draft a "is your site actually using its CMS?" WordPress-vs-static decision scorecard for clients — #things - [ ] Add the "inventory before design + mandatory QA" agent-migration playbook to the migration resource — #things <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Articles/Migrating From WordPress to Astro.md|Migrating From WordPress to Astro by billerickson.net]] ## Highlights - WordPress is not always the right solution for a website. ([View Highlight](https://read.readwise.io/read/01kvkrnvy55npm94hhapgkjfjy)) - Note: H1 — the stated-against-interest thesis from a 20-year WordPress developer: WordPress isn't always the right tool. - Tags: atom/literature/h1, wordpress - Astro is a good fit when the public site is mostly static and the editing workflow does not need to happen in a CMS. ([View Highlight](https://read.readwise.io/read/01kvkrny601n2ydxxhq0m7sct5)) - Note: H2 + Permanent: the WP-vs-static decision turns on how a site is *edited*, not what it contains — a CMS's cost is justified only when its editorial workflow is actually used. - Tags: atom/zettel/z1, wordpress, atom/literature/h2 - The first step is not design. It is inventory. ([View Highlight](https://read.readwise.io/read/01kvkrp03gwnaj71cad07m2chy)) - Note: H3 — migration methodology: inventory the existing site before any design/build work. - Tags: wordpress, atom/literature/h3 - 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: ([View Highlight](https://read.readwise.io/read/01kvkrp1q06cgv2xjcnrzhhkht)) - Note: H4 — the AI silent-failure trap: the first migration pass moved visible content but left broken functionality as dead static markup — QA is load-bearing. - Tags: wordpress, atom/literature/h4