the writing seo, aeo & geo 17 min updated

WordPress to Astro migration: when it makes sense and how to keep your SEO

A WordPress to Astro migration suits content-heavy sites where editors can work headless. Here is the nine-step route that keeps your URLs, metadata and rankings.

A rocket carrying a browser window lifts off from a stack of page cards toward a ringed planet and stars.

A WordPress to Astro migration is worth doing for content-heavy sites where speed matters and editors can work headless. It is the wrong move if you depend on WordPress plugins or a non-technical admin workflow. Below is the decision rule, the two migration paths, and nine steps from audit to post-launch monitoring that keep your URLs and rankings intact.

I have moved enough content sites off WordPress to know the move is not free, and it is not always right. Astro renders content to static HTML and ships no JavaScript to the browser unless you ask for it, so a heavy WordPress blog can become a much lighter site. Astro is a framework, not a CMS, and that trade sits at the centre of every WordPress to Astro decision. This site runs on Astro (content in Supabase, deployed on Netlify), so I am not neutral on the framework. I am still happy to tell you when to leave it alone.

The short version: a WordPress to Astro migration pays off for content-heavy, performance-critical sites where editors can work headless. Skip it when forms, memberships, e-commerce or bookings run through plugins, or when non-technical editors need the full admin to publish.

When the move makes sense

Astro earns its place when the site is mostly content and speed matters: marketing sites, docs, blogs, and publishers where Core Web Vitals feed both rankings and conversion. It also wins when you are tired of plugin sprawl, security patching and a hosting bill that scales with traffic. If your team is comfortable with Git and Markdown, or you keep WordPress as a headless editor behind the scenes, the workflow holds up.

Bar chart of the share of origins passing all Core Web Vitals in September 2026: Astro 71.1 percent on mobile and 84.6 percent on desktop, Next.js 35.7 and 56.9 percent, WordPress 48.3 and 53.7 percent, with mobile gains since September 2025 of 9.5, 7.6 and 3.4 points
Field data from HTTP Archive, September 2026. Astro leads, but its sites skew small and simple.

Does the data back the speed argument? Partly. Astro's own homepage charts the share of real-world sites with good Core Web Vitals, using HTTP Archive and Chrome UX Report data: Astro 71%, WordPress 48%, Gatsby 45%, Next.js 35%, Nuxt 28%. The September 2026 HTTP Archive Tech Report (mobile, all origins, pulled 5 November 2026) gives the same picture in more detail.

Metric (mobile, September 2026)AstroNext.jsWordPress
Origins passing all Core Web Vitals71.1%35.7%48.3%
Origins passing, desktop84.6%56.9%53.7%
Good LCP81.1%53.5%55.4%
Good TTFB63.1%45.6%22.9%
Good INP85.0%59.7%90.3%
Good CLS93.6%73.5%87.3%
Median page weight1.36 MB2.17 MB2.72 MB
Median JavaScript409 KB822 KB677 KB

Source: HTTP Archive Core Web Vitals Technology Report, September 2026 dataset, linked above. The Astro pass rate covers 47,277 tested origins, against 395,345 for Next.js and 2,658,175 for WordPress. A year earlier, in September 2025, the mobile pass rates were 61.6% for Astro, 28.1% for Next.js and 45.0% for WordPress. The April 2026 dataset, as reported by Bitdoze, had Astro at about 67% against about 49% for WordPress, with a median Lighthouse score of 68 for Astro and 44 for WordPress.

The caveats matter more than the headline. This is correlation across very different sites. Astro skews towards small content sites, and Next.js towards heavy applications. Straffe Sites is explicit that its Astro versus Next.js figure is field data, not proof that Astro is better for every project. CodeCaste notes the same report says Astro sites tend to be simpler, so the gap may narrow as a site gets more complex. Bitdoze adds that page weight alone does not predict Core Web Vitals: Shopify has the heaviest pages (3.77 MB median) and still passes on about 79% of sites.

Look at the table again and WordPress beats Astro on good INP (90.3% against 85.0%). The real WordPress weakness is TTFB, where only 22.9% of origins are good. That is largely caching and hosting configuration, which you can often fix without rebuilding anything. The thresholds you are chasing, per CodeCaste, are LCP of 2.5 seconds or less, INP of 200 milliseconds or less and CLS of 0.1 or less.

The speed case is real but not magic. A framework switch alone will not rescue a site with a bloated design and a pile of third-party scripts. This is the same calculus I walk through in WordPress vs Next.js: when each is the right call. Astro slots in as the static-first option when you do not need a full application framework.

When to stay on WordPress

Do not migrate if your site leans on a stack of plugins for forms, memberships, e-commerce or bookings. Do not migrate either if non-technical editors need the full WordPress admin to publish without a developer. The Astro docs say it plainly: you may have to build many existing features yourself instead of installing a third-party plugin. That is real work, and sometimes the right answer is a faster host and a cleaner WordPress build.

WooCommerce deserves its own warning. As CodeCaste points out, Astro will not speed up a WooCommerce checkout, because checkout still runs on WordPress or another back end. Putting a static front end on a shop might help the catalogue pages, but it adds a second system to maintain.

The split is simple, and CodeCaste's FAQ states it well: Astro is stronger for performance-focused, developer-managed sites, while WordPress is stronger when content management, plugins, integrations and non-technical editing matter. I wrote about the same trade-off in WordPress vs Next.js in 2026, and the logic is identical for Astro.

Unsure which side you sit on? The WordPress stack advisor walks through plugins, editors and traffic and tells you whether to fix, go headless or leave. If you already know you want out, start here.

Two migration paths

Full migration: move every post and page into Markdown or MDX files inside the Astro project, define them as content collections, and rebuild your templates as Astro components. WordPress stores content in a database and Astro uses individual files, so this is a genuine change of how content lives. The result is a static site with no live WordPress dependency. Best for sites whose content changes on a human schedule, edited by people who are happy in Git.

Diagram mapping WordPress pieces to Astro: posts and pages to content collections, permalinks to a [...slug].astro route, PHP templates to layouts and components, media library to astro:assets, Yoast fields to frontmatter, form plugins to host form handling, search plugin to Pagefind, Redirection plugin to a _redirects file
Eight things WordPress did for you, and where each one lives after the move.

Headless WordPress: keep WordPress as the editor and pull content into Astro at build time. Astro's own docs describe WordPress as a headless CMS, using the built-in REST API at [YOUR_SITE]/wp-json/wp/v2/ or, optionally, GraphQL through WPGraphQL or Gato GraphQL. Editors keep the admin they know, and you get the static front end. I documented a working version in Headless WordPress plus Astro.

A few facts about the headless route that save you debugging time:

  • The REST API is available without authentication by default for fetching data, and it does not let anyone modify data or site settings.
  • The _fields parameter trims the response to what you need, and _embed pulls in related resources such as the featured image.
  • Custom Post Types only appear in the API if you configure them or give them REST API support. Posts and pages come for free; your "Case studies" type does not.
  • Astro suggests build-time collections wherever possible. Live collections (added in astro@6.0.0) have no MDX support and no image optimisation.

Since astro@5.0.0, a collection takes a loader , and a loader can be a plain function that fetches from an API. That is how you connect the REST API to a typed collection rather than calling fetch inside every page.

A short decision rule. Ask who publishes after launch. If the answer is developers or a very small team comfortable with Markdown, do the full migration. If the answer is an editorial team that will not give up the dashboard, go headless. If the honest answer is "customers, through forms, accounts and checkouts", stay on WordPress and fix the host and theme.

The migration, step by step

The next six steps cover the build. Steps 7 to 9 sit under the SEO section, because that is where rankings are won or lost. For a blog or brochure site, a developer who has used Astro before can work through all nine in a few days (my estimate, not a sourced figure).

Flow diagram of the nine migration steps: audit and crawl, export content, content collections, images, routes, plugin features, redirects, SEO carry-over, launch and monitor
Nothing goes live until steps 7 and 8 are done.

Step 1: Audit and crawl the old site

Before you touch Astro, write down what exists. Crawl the live site and export a list of every indexable URL, including pagination, category and tag archives, and any attachment pages. Then pull your top pages by clicks from Search Console. Those pages are your test set: if they rank today, they must still rank in a month.

Record the following for each URL:

  1. The title tag, meta description and canonical, as set in Yoast or Rank Math (or the theme).
  2. The H1, slug and publish date.
  3. Structured data currently output on the page.
  4. Whether the page is noindexed.
  5. Which plugin renders any front-end feature on it: a contact form, a gallery, a table of contents, a related-posts block.

That last item gives you the real scope. Every plugin on the list is either dropped, replaced (step 6) or a reason to reconsider the whole migration.

Step 2: Export the content

You have three options. In WordPress, go to Tools > Export and download the WXR file. It carries your posts, pages, comments, custom fields, categories and tags, but not the media files themselves. Those need a separate copy from wp-content/uploads, which matters in step 4. Check the WordPress export screen documentation for what each export choice includes.

Second, the Astro migration guide points to wordpress-export-to-markdown, which turns that export into Markdown files with frontmatter. The same guide warns that large or complicated sites may need adjustments to the result. Believe it. Run the tool on a copy, open five posts of different types, and compare them against the live pages before you trust the rest.

Third, you can fetch through the REST API, which is the natural choice for the headless path and a reasonable way to script a one-off conversion. The API paginates, so loop through the pages rather than assuming one request returns everything.

Whichever route you take, remember the Markdown support gap: the Astro docs note that Markdown in WordPress requires a plugin, so your content is stored as HTML and Gutenberg markup. The converter does its best with that.

Step 3: Build the content collections

Create src/content.config.ts and define a blog collection. Per the API reference, every collection uses a loader, and the usual one for files is glob() with a pattern like **/*.md and a base folder. The schema is optional and uses Zod. Write one anyway. A schema fails the build when a post is missing a title, which is exactly what you want during a migration.

Frontmatter fields worth keeping:

  • title , date and slug
  • excerpt
  • categories and tags
  • seoTitle and seoDescription
  • canonical
  • featuredImage, ideally with alt text

Keep the old slug as an explicit field even when it matches the filename. It becomes your source of truth for URL parity in step 5. Keep the SEO title separate from the H1 too, because on most WordPress sites they differ and you do not want to overwrite hundreds of tuned titles with the post heading.

Then comes the clean-up, and this is where time goes. Search the converted files for leftover Gutenberg block comments, raw shortcodes that now print as literal text (galleries, form embeds, table of contents tags), and inline styles from the page builder. Searching for the common shortcode names, such as [gallery or [contact-form, catches most of them. Fix patterns with a script, then fix the odd ones by hand.

If you plan to embed components inside posts, use MDX for those files. Otherwise plain Markdown is faster to build and easier for everyone to edit. The 5.0 release notes claim content collections build up to 5x faster for Markdown and up to 2x faster for MDX, with memory use cut by 25-50%, which is one more reason to default to Markdown.

Step 4: Move the images

The export file contains references to images, not the images. Copy the uploads folder into the project, either under src/assets so Astro can process it or in public if you must keep the old file paths. Then use the astro:assets utilities (the <Image /> component and friends, covered in the Astro images guide) so each image gets width and height, responsive sizes and modern formats. Explicit dimensions are what stop layout shift, and CLS is one of the three metrics you are being measured on.

Decide this trade-off early. Images in public keep their /wp-content/uploads/... style paths, which protects any inbound image links and Google Images traffic. Images under src/assets are optimised and get hashed filenames, so those old paths break. For image-heavy sites I keep a redirect rule for the old uploads path, or leave the high-traffic images where they are.

Rewrite image URLs inside the Markdown at conversion time. Hotlinks to the old WordPress domain keep working only until you switch WordPress off.

Step 5: Routes and URL parity

Content files no longer become pages automatically. As the Astro tutorial explains, you create a route such as src/pages/posts/[...slug].astro to generate them, with getStaticPaths() and getCollection('blog') doing the work. The rest parameter is the useful bit: it lets one route reproduce nested WordPress permalinks, including date-based structures like /2024/05/post-name/, if you feed it the stored slug field.

Reproduce the permalink structure exactly. That means three details people forget:

  • Trailing slashes. WordPress usually ends URLs with a slash. Set Astro's trailingSlash and build format to match, then confirm what your host serves.
  • Archives and pagination. Build category and tag archives with getStaticPaths(), and generate pagination at the same paths WordPress used, such as /page/2/. A dynamic [...page] route handles this.
  • Feeds and sitemap. Use `@astrojs/rss ` for the feed and @astrojs/sitemap for the sitemap (it needs the site option in your config). If your old feed lived at /feed/, either match that path or redirect it in step 7.

Then compare. Run a script over your step 1 URL list against the built dist folder and print every URL that has no matching file. That list is the redirect work, and it should be short.

Step 6: Replace what the plugins did

This is the section the "migrate in three hours" posts skip. Every plugin you listed in step 1 needs a decision.

  • Forms. Use your host's form handling, or a form endpoint service, or an Astro API route. The docs include recipes for HTML forms and for verifying a captcha. Test the thank-you page and the spam protection before launch, not after.
  • Site search. Pagefind is the usual no-plugin answer for a static site: it indexes your built HTML at build time and serves the search from static files. No database, no search plugin.
  • Comments. Choose one of three: archive the old comments as static text on each post, move to a hosted comment service, or switch comments off. Most small business sites will not miss them. Do not leave a comment form that posts nowhere.
  • Analytics. Add the tracking snippet once in your base layout. This is the easiest replacement on the list, and the easiest to forget, so put it on your launch checklist.

If this list is longer than you expected, that is information. A site with a dozen plugin-driven features is a headless candidate or a stay-put candidate, not a weekend migration.

How to keep your SEO through the move

The migration itself is where rankings get lost, almost always through broken URLs. Everything below is about making sure Google meets the same pages at the same addresses, or a clean permanent pointer to the new ones. Keep slugs identical where you can, because the cheapest migration is the one where the URLs never move. If the domain stays the same, the Astro docs add one reminder: update your domain at your host so the site keeps the same URL.

Step 7: Redirects

Map every old WordPress URL to its new path, and serve a 301 redirect for anything that changes, with no chains longer than one hop. Google's documentation lists HTTP 301 and 308 as permanent redirects, which show the new target in search results. Temporary redirects (302, 303, 307) show the source page instead, so a temporary redirect on a permanent move leaves the old URL ranking in place of the new one. Server-side redirects have the highest chance of being interpreted correctly.

For a large site, build the mapping in a spreadsheet and follow my redirect map guide. Chains happen when you redirect old URL A to B, and B later moves to C. Resolve every row to its final destination before it goes live.

Where the rules live depends on the host:

HostWhere redirects go
NetlifyA _redirects file in your published output, or netlify.toml
Cloudflare PagesA _redirects file in your build output
VercelThe redirects array in vercel.json
Any host, static buildAstro's redirects config, which writes meta refresh pages

That table tells you where the rules go, not how many you can have. Each platform caps how many redirects a file may hold and has its own rules for splats and placeholders, so check the current limits in the Netlify, Cloudflare Pages and Vercel docs before you generate a file with hundreds of lines. A very large redirect list may need a different mechanism than a flat file.

About the last row. Google reads a 0-second meta refresh as permanent and a delayed one as temporary, but it recommends a permanent server-side redirect whenever possible. Treat Astro's built-in redirects as the fallback and the host's redirect file as the primary route.

Two things trip people up. First, /feed/ and its variants, such as category and comment feeds, which readers and aggregators still request for years. Second, attachment URLs: WordPress can serve a page for every uploaded image, and those URLs may have collected links or even impressions. Redirect them to the parent post or the image itself. Your Search Console and crawl data from step 1 will tell you which of these actually matter.

If you want a head start, the WordPress.org 301 Redirects plugin has a 404 error log that records timestamp, URL and user-agent (no user IPs) and supports import and export of bulk redirects. Run it on the old site before launch to catch URLs your crawl missed. It requires a non-default permalink structure.

Step 8: Carry over the SEO layer

Redirects get visitors there. Parity keeps them ranking. For every page, carry over:

  • Titles and meta descriptions, from the seoTitle and seoDescription fields you kept in step 3.
  • Canonical tags, self-referencing by default and matching the final URL, trailing slash included.
  • Structured data. Yoast or Rank Math probably output Article, Organization and breadcrumb markup without you noticing. Astro does not write your schema for you, so add the JSON-LD to your layouts and validate a sample.
  • Robots rules. Recreate robots.txt in public/, and carry over noindex for anything that was noindexed: internal search results, thin archives, author pages. Dropping a noindex by accident can flood the index with pages you never meant to show.
  • hreflang, if the site is multilingual. WPML and Polylang generate these alternates automatically, so you must reproduce them, with reciprocal links between each language version.
  • The XML sitemap, generated by @astrojs/sitemap and submitted in Search Console.

Google also publishes guidance for site moves with URL changes. Read it before launch day and follow its order of work. I keep a longer pre-launch list in my site migration SEO checklist, and the wider technical SEO work sits around it.

Step 9: Deploy, launch and monitor

Deploy to a staging URL first and block it from indexing. Then run through this list:

  1. Crawl staging and compare every URL against the step 1 list. Each old URL should return 200 or a single 301 to a 200.
  2. Spot-check the top pages from Search Console: title, description, canonical, schema, images, internal links.
  3. Submit a form, run a search, load the feed, check analytics fires.
  4. Confirm the sitemap lists only canonical URLs and that robots.txt does not block the whole site (it happens).
  5. Switch the domain, then re-crawl production the same day.

After launch, the monitoring window begins. Watch the Search Console Pages report for new errors and the crawl stats for spikes in 404s. Re-crawl against the old list weekly at first. Keep the old WordPress export and a database backup somewhere safe until you are sure nothing was missed.

Expect some noise. Google's documentation notes that after a redirect it may occasionally show old URLs as alternate names, which is normal and fades as users get used to the new addresses. A redirect that works shows up as the new URL in results over time. A 404 does not fix itself, so chase every one.

How long it takes

Rough effort, and this is my estimate, not a sourced fact: a small blog is a few days, and a content site with custom templates, hundreds of posts and a redirect map is a few weeks. The variable is rarely the content export. It is rebuilding templates, replacing plugin features and testing the redirects before launch. If your step 6 list is long, add time there first.

If you want a second opinion on scope before you commit, talk to me about leaving WordPress.

FAQ

Should I use a 301 or a 308 redirect?

Either works for Google, which treats both as permanent redirects. In practice most hosts default to 301 in their redirect files, and that is fine. Avoid 302 and 307 for a permanent move, because they tell Google to keep showing the old URL.

Why do old URLs still appear in Google after the migration?

Google's documentation says it may occasionally show old URLs as alternate names after a redirect. That is normal and fades as people get used to the new addresses. If an old URL still shows after a long wait, check that it returns a single 301 and not a chain or a temporary redirect.

Should I use Markdown or MDX for migrated posts?

Use plain Markdown unless a post needs an interactive or custom component inside the text. The Astro docs list Markdown and MDX among the built-in loader formats, and the 5.0 announcement says Markdown collections build faster than MDX ones. Convert to Markdown first and promote individual posts to MDX when they earn it.

Do I need server-side rendering to run redirects on Astro?

No. A static build can serve redirects from the host's own redirect file, which is the route Google prefers anyway. Astro's redirects option also works on static output, but it falls back to meta refresh pages. Reserve SSR for features that need a server at request time, such as personalised pages.

Should I keep WordPress running after launch?

On the headless path, yes: WordPress is your editor and has to stay up and secured. On a full migration, keep it offline or behind a password until your crawl and Search Console checks come back clean, then archive the backup. Do not leave an old public WordPress copy at the same content URLs, because it creates duplicate pages.

this post in the tree

Need this done, not just read?

Discuss your website Book 30 minutes