DEV Community

Cover image for How I move 300 WordPress posts into Astro content collections
Linc
Linc

Posted on

How I move 300 WordPress posts into Astro content collections

Last month I moved a client with about 300 blog posts off WordPress. The design was the easy bit. The content is what eats your week if you dont plan it. Here is the workflow I use now for getting those posts into Astro content collections.

1. Export, then look before you convert

I export the WordPress XML from Tools > Export and also pull the posts through the REST API (/wp-json/wp/v2/posts?per_page=100). The XML has the raw content, the API gives me clean fields for slug, date, categories and featured image id. Both go in a migration/ folder in the repo.

Before converting anything I open ten random posts and check what is actually in them. Page builder shortcodes, [gallery], embedded forms, inline styles. You want to know that before you write a converter, not after.

2. Convert to Markdown, keep the frontmatter boring

A small Node script with turndown does HTML to Markdown. Each post becomes src/content/blog/<slug>.md with frontmatter like this:

title: "Post title"
pubDate: 2023-04-12
updated: 2024-01-03
description: "First 150 chars or the Yoast description"
category: "news"
cover: "./images/post-slug.jpg"
oldUrl: "/2023/04/post-slug/"
Enter fullscreen mode Exit fullscreen mode

The oldUrl field is the one people skip. It lets me generate the /_redirects file straight from the content, so every old permalink 301s to the new one. No spreadsheet needed for blog posts.

3. Define the collection schema first

In src/content.config.ts I define the collection with Zod and make most fields required. If a post is missing a date or a description the build fails and tells me which file. Way better than finding out from the client after launch.

4. The stuff the converter always gets wrong

  • Images with hard coded wp-content/uploads URLs. Download them, move them next to the content, rewrite the paths.
  • Galleries and shortcodes. I flag them in a list for manual review instead of trusting the converter.
  • Smart quotes and weird non breaking spaces. One replace pass fixes it.
  • Internal links still pointing at the old domain or ?p=123 style URLs. Grep for them and map them through the same old to new list.
  • Comments. Work out real discussion vs spam, agree with the client what to keep, and keep the export instead of silently dropping them.

5. Let the coding agent do the boring bit, but check its work

I give Claude Code the converter script, the schema and one rule: after the conversion, run astro build, then crawl dist/ and list any post where the word count is under 50% of the original. That catches posts where the converter ate half the content. Word count is only a warning sign though, so I still eyeball headings, embeds and a few of the long posts.

6. Preview and ship

Once the build is clean I deploy a preview and click through the archive pages, a handfull of old URLs and the RSS feed. I host these on Novence so it is just npx novence deploy from the project folder, and it sits next to all the other client sites. Then I run the old URL list against the preview with curl and make sure everything returns a 301 to a page that returns 200.

What I would tell myself on the first migration

Spend your time on the audit and the schema. The conversion script is the small part. If the content is clean going in, the rest of the project is quiet, and the client never notices the move except that the site got faster.

Top comments (3)

Collapse
 
bealinawaz profile image
Ali Nawaz •

The oldUrl field is a nice touch. Two REST details that can save a step in the export:

  • featured_media is only an ID, so add _embed to the request (/wp-json/wp/v2/posts?per_page=100&_embed) and the image URL comes back inline under _embedded, no second request per post.
  • If the site runs Yoast, every post in the REST response also has a yoast_head_json field with the meta description, canonical and the Open Graph image, so you get the Yoast description without parsing the XML.

One gotcha: /wp/v2/posts only returns published posts of the post type. Pages and custom post types have their own endpoints, and drafts or private posts need an authenticated request with a status filter, so it's worth counting the results against the XML before you trust the API side.

Collapse
 
wbcomdesigns profile image
Wbcom Designs ๐Ÿ’ก •

Opening ten random posts before writing the converter is the step most people skip. Two things that bit us on similar moves: comments (export them or decide on purpose to drop them, since some posts rank on the comment thread), and image URLs inside the content that point at dated /wp-content/uploads/ paths.

A redirect map for those keeps old image links and hotlinks working. Did you keep the original permalinks, or redirect to a new slug pattern?

Collapse
 
officialmailkr profile image
์˜คํ”ผ์…œ๋ฉ”์ผ •

oldUrl์„ ์ฝ˜ํ…์ธ ์— ๋‚จ๊ฒจ ๋ฆฌ๋‹ค์ด๋ ‰ํŠธ๊นŒ์ง€ ์ƒ์„ฑํ•˜๋Š” ํ๋ฆ„์ด ์ข‹๋„ค์š”. ๊ธ€์ž ์ˆ˜ ๊ฐ์†Œ๋ฅผ ๊ฒฝ๊ณ ๋กœ๋งŒ ์“ฐ๊ณ  ์ œ๋ชฉยท์ž„๋ฒ ๋“œ๋ฅผ ๋ˆˆ์œผ๋กœ ํ™•์ธํ•œ๋‹ค๋Š” ๊ตฌ๋ถ„๋„ ์ค‘์š”ํ•ด ๋ณด์—ฌ์š”. ์ด์ „ URL ๊ฒ€์ฆ์—๋Š” ๋ฆฌ๋‹ค์ด๋ ‰ํŠธ ์ฒด์ธ์ด ์ƒ๊ธฐ๊ฑฐ๋‚˜ ์ฟผ๋ฆฌํ˜• ๋งํฌ๊ฐ€ ์—‰๋šฑํ•œ ๊ธ€๋กœ ๊ฐ€๋Š” ๊ฒฝ์šฐ๋„ ๋„ฃ์œผ๋ฉด, 301๊ณผ ์ตœ์ข… 200๋งŒ์œผ๋กœ ๋†“์น˜๋Š” ๋งคํ•‘ ์˜ค๋ฅ˜๋ฅผ ๋” ์žก์„ ์ˆ˜ ์žˆ๊ฒ ์Šต๋‹ˆ๋‹ค.