# How do I convert a WordPress blog to Astro?

> Export each WordPress post to an MDX file with front matter (title, slug, date, excerpt, tags) and the body as clean Markdown, keep the slugs so URLs barely change, and render the files through an Astro content collection. Astro outputs static HTML, so the blog becomes fast and clean. Then 301 any URL that does change. WPBuildAI exports the posts to MDX and rebuilds the blog in a static stack, with redirects and metadata intact.

Source: https://wpbuildai.com/convert-wordpress-blog-to-astro-mdx-export/
By lawrence-arya · 2026-06-03

---
To convert a WordPress blog to Astro, you turn each post into an MDX file and let Astro render it as static HTML. Concretely: export each post with front matter (title, slug, date, excerpt, tags) and the body as clean Markdown, keep the slugs so your URLs barely change, and render the files through an Astro content collection. The result is a blog that loads fast and is trivial for crawlers to read. Anything whose URL does change gets a 301. WPBuildAI exports the posts to MDX and rebuilds the blog in a static stack, with redirects and metadata intact.

Export from a settled version rather than mid-cycle: [WordPress 7.0 shipped on 20 May 2026, with 7.0.1 on 9 July and a 7.0.2 security release on 17 July](https://wordpress.org/news/category/releases/), and post content that round-trips cleanly on one release can pick up block markup differences on another.

## Why Astro suits a blog

Astro ships static HTML with little or no client-side JavaScript, which is close to ideal for a content site. The 2024 [Web Almanac](https://almanac.httparchive.org/en/2024/) documents how heavy the average WordPress page has become with themes and plugins, and a static Astro build sheds almost all of it. That speed shows up directly in [Core Web Vitals](https://web.dev/articles/vitals), and Portent's study of [site speed and conversion](https://www.portent.com/blog/analytics/research-site-speed-hurting-everyones-revenue.htm) shows how much that speed is worth, while a fast, server-rendered page is also the easiest thing for search and AI engines to read in full. A blog is mostly text and images, exactly what static rendering handles best: there is little dynamic behaviour to give up, so you gain the speed and lose almost nothing. For a content site whose job is to be read and ranked, that trade is heavily in favour of static.

## MDX versus plain Markdown

The format choice is about how much each post needs beyond prose. Plain Markdown is enough for straight writing, headings, paragraphs, lists, links, images. MDX is Markdown that can also embed components, so it suits posts that use callouts, interactive embeds, custom diagrams, or reusable blocks, while keeping the prose itself in clean Markdown. Astro reads both through a content collection, so you are not locked in: you can keep most posts as Markdown and reach for MDX only where a post genuinely needs a component. The practical advice is to default to Markdown for simplicity and use MDX where interactivity earns it, rather than converting everything to MDX reflexively. The body stays clean and writer-friendly either way, which is part of why an Astro blog is pleasant to maintain after the move.

## The export, step by step

1. **Export each post to MDX** with front matter (title, slug, date, excerpt, tags) and a clean Markdown body.
2. **Keep the slugs**, so most URLs are unchanged.
3. **Move the images** into Astro's asset pipeline and update references.
4. **Render with a content collection**, which types the front matter and builds each post.
5. **301 any changed URL** and resubmit the sitemap.

MDX is worth choosing per post when it uses callouts, embeds, or custom components; plain Markdown is fine for straight prose. The clean-export step, stripping WordPress theme and shortcode markup down to real content, is the same as in [converting Elementor to static HTML](/convert-wordpress-elementor-to-static-html/), and the media handling mirrors [migrating images without broken links](/blog/how-to-migrate-wordpress-images-and-media-without-broken-links/).

## A worked example: a 200-post blog to Astro

Picture a 200-post WordPress blog moving to Astro. A crawl-and-export turns each post into an MDX file: the front matter carries the title, original slug, publish date, excerpt, and tags, and the body is the post's content converted from WordPress's HTML to clean Markdown, shortcodes resolved, theme wrappers gone. Images are pulled into Astro's `assets` directory and the references updated so they are optimised at build time. A single content collection types all 200 files and builds them into static pages at URLs that match the old slugs. Internal links between posts are rewritten to the new paths. The handful of URLs that changed get 301s. The result is a blog that builds to static HTML, loads in well under a second, passes Core Web Vitals, and keeps its rankings because the slugs, and therefore the URLs, stayed stable. The export was the work; the build was almost free.

## Keeping slugs and URLs stable

The single most important decision for rankings is to keep the slugs, because the slug is what determines the URL, and the URL is what holds the ranking. If your WordPress posts lived at `/blog/my-post/` and your Astro content collection renders them at `/blog/my-post/` too, then most of your URLs simply do not change, and there is nothing to redirect for those, the safest possible migration. Carry each post's original slug in its front matter and configure the Astro route to use it, rather than letting a new system generate fresh slugs. Where a slug must change, for a genuine cleanup, you redirect it deliberately. The principle is to minimise URL change first and redirect what is left, which is far safer than changing every URL and relying on a complete redirect map to catch them all. Stable slugs turn most of the migration into a no-op for SEO.

## Handling images and internal links

Two things break quietly if you skip them. Images: a WordPress blog references images from its media library, so if the Astro build points at the old WordPress image URLs, those images vanish when WordPress is retired. Pull every image into Astro's asset pipeline so it is hosted with the new site and optimised at build, and update each reference. Carry the alt text too, for accessibility and image search. Internal links: posts that link to each other by old WordPress URLs should be rewritten to the new paths, which is straightforward when you kept the slugs because the paths mostly match. Leaving internal links pointed at old URLs works only as long as the redirects catch them, adding a needless hop; rewriting them to the final paths is cleaner. Handling media and internal links deliberately is what keeps the converted blog free of broken images and dead links.

## The content collection: typed front matter

Astro's content collections are what make an MDX blog robust to maintain, so it is worth using them properly. A collection defines a schema for the front matter, the expected fields and their types, so every post is validated at build: a missing title or a malformed date fails the build rather than shipping broken. You define the collection once with the fields your posts use, title, slug or an inferred one, date, excerpt, tags, and Astro types and renders every matching file. This is a real upgrade over WordPress, where nothing enforces that posts have consistent metadata. The typed schema also gives you confidence at scale: across 200 posts, the build guarantees each has valid front matter, so you catch a malformed post immediately instead of discovering it live. For a blog you will keep adding to, that validation is a quiet but real benefit of the Astro model.

## Keeping the rankings

The move protects rankings when slugs stay stable, metadata carries into the front matter, and changed URLs get 301s, the core of Google's [site move guidance](https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes). Carry each post's title and meta description into the front matter so the rendered pages keep the same on-page signals, and resubmit the sitemap after launch so the static pages are discovered. Because Astro renders static HTML that crawlers and AI engines read in full without executing JavaScript, a careful conversion usually improves rankings through speed rather than risking them, the broader case in [page builder vs headless for SEO](/wordpress-page-builder-vs-headless-cms-for-seo/) and [moving blog posts without losing rankings](/blog/how-to-move-wordpress-blog-posts-without-losing-rankings/). The risk in this migration is narrow and specific: dropping URLs or metadata. Keep both and the move is close to risk-free, with the speed gain as upside.

## Common mistakes converting to Astro

The recurring errors are avoidable. Letting the new system generate fresh slugs changes every URL and forces a full redirect map where keeping slugs would have avoided most of it. Leaving images referenced on the old WordPress domain breaks them when it is retired. Forgetting to carry titles and meta descriptions into the front matter thins the pages to search engines. Skipping the content-collection schema means malformed posts ship instead of failing the build. And converting messy WordPress HTML without cleaning it, shortcodes and all, fills your MDX with noise. Each is avoided by the same discipline: keep slugs, re-host media, carry metadata into typed front matter, clean the body to real Markdown, and 301 only what genuinely changed, which makes the Astro conversion a fast, ranking-safe upgrade.

## Key points to remember

Convert a WordPress blog to Astro by exporting each post to an MDX (or Markdown) file with front matter and a clean Markdown body, keeping the original slugs so most URLs do not change, and rendering through a typed Astro content collection that validates every post at build. Re-host images in Astro's asset pipeline, rewrite internal links to the new paths, carry titles and meta descriptions into the front matter, and 301 only the URLs that genuinely change. Astro's static HTML makes the blog fast and easy for crawlers and AI engines to read, so a careful move improves rankings through speed rather than risking them. WPBuildAI exports the posts to MDX and rebuilds the blog static with redirects and metadata intact; send your site URL for a fixed quote.

Not affiliated with WordPress or Lovable.