Migrating WordPress to a Static Site Generator

WordPress powers a large share of the web, and many of those sites are a blog or a documentation set that changes a few times a week: no shop, no memberships, no dynamic features beyond comments and a contact form. For those sites, a static generator removes the PHP runtime, the database, the plugin update treadmill and the security patching, and typically makes every page several times faster. The migration is not a one-click export, though. WordPress content carries shortcodes, block markup, media URLs, comment threads and a URL history that search engines and other sites depend on.

This guide migrates a 1,850-post technical blog from WordPress to Astro, keeping every URL, localising 6,400 media files, preserving comments, and measuring the before and after. It follows the playbook in Migrating Between Static Site Generators; the generator choice itself is covered in the SSG Framework Selection Matrix.

Prerequisites

• Admin access to the WordPress site, or at least its REST API and uploads directory.
• A full crawl or sitemap of current URLs — including categories, tags, pagination and attachment pages.
• A decision on who edits content afterwards: developers in Git, writers through a Git-backed CMS, or WordPress kept as a headless CMS.

Step 1: Export Content

The REST API gives structured data that is easier to convert than the WXR export file:

// scripts/wp-export.mjs
const base = 'https://blog.example.com/wp-json/wp/v2';
let page = 1, posts = [];
while (true) {
  const r = await fetch(`${base}/posts?per_page=100&page=${page}&_embed=1&status=publish`);
  if (!r.ok) break;
  posts.push(...(await r.json()));
  if (page++ >= Number(r.headers.get('x-wp-totalpages'))) break;
}
// posts[i]: { slug, date, modified, title.rendered, content.rendered, categories, tags, link, _embedded }

Convert HTML bodies to Markdown with turndown, adding rules for what WordPress emits: [caption] wrappers become figures, Gutenberg code blocks keep their language, embeds become a component or a plain link, and gallery blocks become an image list. Anything unrecognised is kept as raw HTML and logged — on this site 43 posts needed hand attention, mostly old plugin shortcodes.

td.addRule('wpCode', {
  filter: (n) => n.nodeName === 'PRE' && n.classList.contains('wp-block-code'),
  replacement: (_, n) => `\n\n\`\`\`${n.querySelector('code')?.className.replace('language-', '') ?? ''}\n${n.textContent}\n\`\`\`\n\n`,
});

Front matter comes from the API fields: title, date, updated date, categories and tags (resolved from IDs), excerpt, featured image and the original post ID, which is useful for redirects.

Step 2: Localise Media

Post bodies reference https://blog.example.com/wp-content/uploads/2021/03/diagram-1024x576.png, often a resized variant. Download the original of each referenced image, store it next to the post (or in src/assets/), and rewrite references to local paths so Astro's image pipeline generates modern formats and sizes:

grep -rhoE 'https://blog\.example\.com/wp-content/uploads/[^"'"'"' )]+' src/content/posts \
  | sed -E 's/-[0-9]+x[0-9]+(\.[a-z]+)$/\1/' | sort -u > media.txt
wc -l media.txt      # 6,412 originals

Stripping the -1024x576 suffix fetches the original upload rather than a WordPress-generated thumbnail, so the new pipeline starts from full resolution. The pipeline itself is described in Image Optimization Pipelines in Astro.

Step 3: Keep Every URL

WordPress permalinks are usually /%year%/%monthnum%/%postname%/. Reproduce them exactly in the generator — in Astro, a src/pages/[year]/[month]/[slug].astro route whose params come from each post's date and slug. Then generate redirects for everything that cannot be reproduced:

• /?p=1234 and /?page_id=56 — WordPress short links, often in old emails and forums. Map post ID to new URL from the export.
• Attachment pages (/2021/03/post-slug/diagram-2/) — redirect to the post.
• Author, date and feed variants you choose not to keep — redirect to the nearest equivalent.
• /feed/ and /category/x/feed/ — keep an RSS feed at /feed/ or redirect.

Query-string redirects need an edge rule or function rather than a _redirects file on most hosts; the redirect mechanics are in Keeping Redirects Working After an SSG Migration. A URL diff between the WordPress sitemap and the new build, run in CI, made "every URL still works" a checked fact: 2,310 old URLs, 1,850 preserved exactly, 460 redirected, 0 broken.

Step 4: Comments, Forms and Search

Comments: 14,200 existing comments were exported from the REST API into one JSON file per post and rendered statically under each article. New comments moved to giscus (GitHub Discussions) loaded on scroll; the old comment count stayed visible so the history was not lost. Contact form: replaced with a serverless function — see Handling Form Submissions on a Static Site. Search: WordPress's database search became Pagefind, as in Adding Pagefind to an Astro Site.

SEO Details That Carry Over

Search visibility depends on more than URLs. Carry across the SEO metadata WordPress plugins stored: Yoast or Rank Math titles and meta descriptions live in post meta (exposed through the REST API with the plugin's fields enabled) and belong in front matter as seoTitle and description. Canonical URLs, noindex flags on thin pages, and Open Graph images should map one to one. Structured data changes shape — a plugin's generic JSON-LD becomes whatever your templates emit — so validate a sample of post types with a schema validator before cutover. Finally, keep publish and update dates exactly as they were; changing every post's date to the migration day looks to readers and search engines like a mass republish. On this site, 1,612 posts had custom meta descriptions, and every one was preserved.

Measured Impact

Organic search traffic dipped 4% in the first two weeks as crawlers processed redirects, then recovered and was 11% above the pre-migration baseline after three months, which the team attributes to the Core Web Vitals improvement and the cleaned-up URL structure.

Pitfalls & Rollback

• Hot-linking old media. Leaving wp-content/uploads URLs in posts ties the new site to the old server. Localise every file.
• Forgetting ?p= links. They are common in older inbound links; map them from post IDs.
• Dropping comments silently. Readers and authors notice. Keep existing threads visible even if new comments move elsewhere.
• Converting in one untested pass. Run the converter on a sample of 50 posts across different years and editors first; WordPress markup changed a lot between the classic editor and Gutenberg, and old posts break different rules.
• Scheduled and private posts. The REST API returns only published posts by default; export drafts, scheduled and private posts separately if they must survive the move.
• No editor plan. If writers used the WordPress admin, give them a Git-backed CMS or keep WordPress headless; see Wiring a Headless CMS to a Static Build.
• Rollback: keep WordPress running, read-only, on a separate hostname until the static site has four clean weeks; switching DNS back is the rollback.

Conclusion

A WordPress-to-static migration is mostly about preservation: every URL, every image and every comment thread readers relied on. Exporting through the REST API, converting with explicit rules for WordPress markup, localising original media, reproducing permalinks and generating one-hop redirects for the rest moved a 1,850-post blog with zero broken URLs — and cut TTFB from 620 to 48 ms, LCP from 3.4 to 1.4 seconds, and hosting cost to zero.

FAQ

How do I get WordPress content into Markdown?

Export with the built-in WordPress export tool or the REST API, then convert the HTML post bodies to Markdown with a converter such as wordpress-export-to-markdown or a small script using turndown. Shortcodes and block markup need custom rules.

What happens to WordPress URLs after migration?

Configure the generator's permalinks to reproduce the WordPress structure exactly, such as /2021/03/post-slug/, and generate redirects for anything that cannot match, including ?p=123 links, category archives and attachment pages.

What replaces comments and contact forms?

Existing comments can be exported into each post's front matter or a data file and rendered statically. New comments can go to a lightweight service, GitHub Discussions via giscus, or be closed. Contact forms move to a host form feature or a serverless function.

Is it worth it for a small blog?

If the site is mostly articles and rarely changes structure, usually yes: hosting becomes free or nearly so, there is no plugin or PHP patching, and pages load several times faster. If non-technical editors depend on the WordPress admin, plan for a CMS or keep WordPress headless.

Related

• Parent: Migrating Between Static Site Generators — the general migration playbook.
• Converting Front Matter at Scale During Migration — scripting the metadata conversion.
• Keeping Redirects Working After an SSG Migration — the redirect map in depth.
• Eleventy vs Jekyll for Markdown-Heavy Blogs — other destinations for a blog.
• Logging 404s at the Edge — catching any URLs the map missed.