Migrating from WordPress to Astro: a step-by-step guide.

Your WordPress site is slow. You know it. Your visitors know it too — and Google figures it out faster than any of them. The question is no longer why, but how to get out without breaking your search rankings.

We cover the complete migration here: content export, rebuilding in Astro, redirects, and monitoring after the switch. No theory — concrete steps, real numbers, and at each step what we did on a site whose redirects you can check for yourself.

What you will lose (and gain)#

Let’s be honest: migrating from WordPress to Astro is not just changing engines. It’s changing philosophy.

What you lose:

• The Gutenberg visual editor (replaced by a CMS such as Decap)
• All-in-one plugins (forms, SEO, cache, galleries)
• The WordPress support community (though Astro is growing fast)

What you gain:

• A site that loads in under one second — by design, not by optimisation
• Zero JavaScript shipped to the browser by default
• No server to maintain, no plugins to update
• A monthly infrastructure cost of EUR 0
• Full ownership of your code (in your Git repository)

The question is not “is it better?”. It’s “is it better for your case?”. We come back to this at the end.

The numbers, not the promises#

The results below consolidate six real, documented, sourced migrations. The Astro4B column reflects measurements on sites we delivered:

Sources: Kashif Aziz (2026), mfyz.com, Pascal Cescato (DEV.to), Kiwop Agency, Perel Web Studio, Devaradise.

A telling case: Kiwop Agency measured a +28% increase in organic click-through rate (CTR) and a Lighthouse score of 97 after migrating to Astro + Payload CMS. Perel Web Studio saw +142% organic traffic within three months.

A measured case: Marrakech City Guide#

Marrakech City Guide is the travel guide published by our founder, Pierre-Marie Coupry. It was running on WordPress when a Google update, in February 2026, cut its impressions from 920 to 300 a day. We migrated it to Astro and put it back online on 17 July 2026, with a new site structure, rewritten content and an English version. It is exactly what we usually advise against: changing everything at once.

Here is what the migration meant on the redirect side:

Each old address leads to the page that now covers its topic, not to a section: /comment-shabiller-a-marrakech-4544 lands on /fr/preparer/que-mettre-valise/, /place-jemaa-el-fna-832 on /fr/lieux/jemaa-el-fna/. You can check it yourself: curl -I on the old address returns the redirect and its destination.

The migration explains the absence of a dip: impressions picked up two days after the switch, because no indexed address was lost. The growth that followed comes from the whole project, the new structure, the rewrite, the English version and the new pages. One limit to keep in mind: the site was starting from a floor. A redirect mistake costs a healthy site far more than a site getting 3 clicks a day.

The full twelve-month curve is on our WordPress rebuild page.

Before you start#

Three conditions for a smooth migration: a complete backup, an inventory of existing URLs, and a list of redirects to set up. URLs are the only thing that can cost you rankings if handled poorly.

The 5 migration steps#

This is the sequence we apply to every migration project at Astro4B, and the one behind our rebuild offer. Order matters: do not move to the next step until the previous one is validated.

Step 1: audit before touching anything#

The migration starts before the first line of code. Open Google Search Console and export every page that receives impressions, not just the ones that receive clicks. A page with no clicks today may be the one that ranks tomorrow. On Marrakech City Guide, the inventory came to 188 old addresses to handle.

Your audit checklist:

• Total number of published pages and posts
• Active plugins and their Astro equivalent (forms, analytics, search, comments)
• Custom fields (ACF, Custom Fields) — exporting them requires a dedicated script
• Current URL structure (date-based /2024/06/slug/ or flat /slug/)
• Yoast/Rank Math meta descriptions and titles (they are not in the standard export)

That last point is the most common trap. Meta descriptions live in the wp_postmeta table, not in the XML export file. Lose them and you lose your Google snippets.

Step 2: carry over the content#

Three methods, each with its strengths:

XML export + Markdown conversion — The most common. WordPress > Tools > Export generates a WXR file. The wordpress-export-to-markdown tool (npm) converts it into Markdown files with frontmatter. Fast and reliable, but it captures neither ACF fields nor Yoast meta.

WordPress REST API — Query /wp-json/wp/v2/posts to retrieve posts with their full metadata. If Yoast is active, each response includes a yoast_head_json field with the page title and description: the simplest way not to lose them. Requires a custom script (Node.js + Turndown for HTML → Markdown conversion).

WPGraphQL — A single query for posts, categories and metadata, versus several REST calls. More efficient on large sites.

For a site under 100 pages, the XML export is more than enough. Beyond that, the REST API or WPGraphQL prevent omissions.

Images: download the entire wp-content/uploads/ folder. Reorganise it under public/images/ and rewrite the paths in your Markdown files. Astro’s <Image> component handles optimisation (WebP, responsive, anti-CLS) at build time.

Carrying content over can also be the moment to rewrite it, as on Marrakech City Guide. But that is then an editorial project on top of the technical one, with its own schedule.

Step 3: rebuild in Astro#

Astro structures content through Content Collections: your posts are Markdown files in src/content/blog/, validated by a Zod schema at build time. An error in the frontmatter? The build fails. No surprises in production.

Each post has typed frontmatter:

title: "My post"
description: "The meta description, 160 characters max"
date: 2026-06-08
category: Migration
tags: [wordpress, astro]
readingTime: "8 min read"

What Astro does natively (no plugin):

• XML sitemap (@astrojs/sitemap)
• RSS feed (@astrojs/rss)
• Image optimisation (astro:assets)
• Markdown and MDX support
• Pagination via paginate() in getStaticPaths()

What you need to add: a content editing tool (see below), client-side search (Pagefind), a comment system (Giscus), a contact form (Formspree or Web3Forms).

A site that takes 4 seconds to load does not get migrated. It gets rebuilt.

The performance gain is visible from the first deployment.

Who will edit the content?

WordPress has a visual editor. Astro has Markdown files. If your editorial team does not know Git, it needs a CMS that plugs into Astro. The market is wide — here are the options by profile:

Decap CMS — Free, open-source, Git-based. Editors work in the browser, files are committed directly to the repository. Ideal for technical teams or blogs with few contributors. It’s our choice at Astro4B.

Storyblok — Visual editor close to WordPress, native Astro integration. From EUR 99/month. The best compromise for teams used to a WYSIWYG editor.

Sanity — Fully customisable schemas, real-time collaboration. Free tier viable in production. For dev teams who want full control.

TinaCMS — Visual editor + Git-based. The best of both worlds, but still young.

The decision is simple: if your editors are technical (or willing to learn), Decap CMS. If they want to click like in WordPress, Storyblok.

One option you will be offered elsewhere: keeping WordPress as a back office only, with Astro reading its content. It works, but you then keep a WordPress server to update and secure, which is what the migration was meant to remove. We do not offer it.

Step 4: redirects, the real issue#

This is where most migrations fail. Every indexed URL that changes without a redirect loses what it had earned in Google. And URLs almost always change: WordPress often uses /2024/06/15/my-post/, Astro typically /blog/my-post/.

Three rules, which are also those of Google’s guide to site moves:

1. One 301 per old URL, to its exact equivalent. Not to a section, not to the home page. Google is explicit: redirecting many old URLs to a single destination may be treated as a soft 404.
2. A 410 for what disappears. A page you are not carrying over should say so: the 410 code signals a permanent removal. On Marrakech City Guide, 37 old pages went out as 410s.
3. Redirects kept for at least a year, again according to Google. The simplest approach is never to remove them.

Redirects not to forget:

• Every post and page (obviously)
• The RSS feed: /feed/ → /rss.xml
• Paginated archives: /page/2/, /page/3/…
• Author and category pages
• Media URLs (images) if they change
• Trailing slashes — a silent source of duplicates

Configuration: a _redirects file at the root (Cloudflare Pages, Netlify). On Cloudflare Pages, Cloudflare’s documentation sets three limits. The file does not read query parameters, so a rule such as /?p=123 never fires. It accepts at most 2,000 static and 100 dynamic redirects. And it only returns redirect codes: for a 410 you need a function or a Worker.

# _redirects — Cloudflare Pages
# Format: SOURCE  DESTINATION  CODE

# One line per old URL, to its exact equivalent
/2024/06/15/my-post/       /blog/my-post/          301
/about-us/                 /about/                 301

# A pattern only when the mapping is mechanical
/category/blog/:slug/      /blog/:slug/            301

# WordPress feed and sitemap
/feed/                     /rss.xml                301
/sitemap_index.xml         /sitemap-index.xml      301
/wp-sitemap.xml            /sitemap-index.xml      301

?p=123 addresses rarely cause trouble: WordPress already redirects them to permalinks, and they are seldom indexed. Check Search Console before spending time on them.

Check production, not your spreadsheet. The mapping file moves during the project. On Marrakech City Guide, 60 of the 140 planned redirects ended up pointing to a different page from the one in the original spreadsheet, and 11 addresses slated for removal were redirected after all. Once live, test every old URL (curl -I in a loop, or Screaming Frog in list mode) and compare what the site returns with what you expect. A single 404 on a high-traffic page can undo weeks of work.

“Migrating a 50-page WordPress site to Astro generally takes 2 to 4 weeks, including one week of SEO testing before the DNS switch.”

— Astro4B estimate, based on 8 migrations completed in 2025–2026

Step 5: go live and monitor#

On launch day, submit your new sitemap to Google Search Console and Bing Webmaster Tools. Then monitor.

Monitoring protocol:

• Week 1 — Daily check: crawl errors, 404 pages, de-indexations
• Weeks 2-4 — Weekly check: rankings, impressions, CTR
• Month 2 — Full review: organic traffic vs pre-migration baseline

Realistic recovery timeline:

• Same URLs + 301s in place: slight fluctuation in weeks 1-2, recovery within 30 days
• URL structure change with 301s: 30 to 60 days
• Botched migration (missing redirects): -40 to -60% organic traffic in week 1

Google itself warns that visibility can fluctuate during a migration, and that a medium-sized site needs a few weeks. On Marrakech City Guide, with an entirely new structure and every indexed address redirected, impressions picked up two days after the switch.

Done well, a migration loses nothing. It gains nothing on its own either: what lifts traffic afterwards is what you change while migrating, structure, content and speed.

When NOT to migrate#

We sell Astro sites. But not at any cost.

Astro excels on content sites: brochure sites, blogs, marketing sites, portfolios. For a SaaS with a dashboard, a marketplace, or a complex transactional site, other frameworks (Next.js, Remix) are better suited.

If you don’t know which category you fall into, this is probably a good time to talk about it.

Frequently asked questions#

You have a WordPress site and recognise yourself in this article? We can rebuild your WordPress site with Astro, content transfer and redirects included. The price is already in the configurator.