Migrate an existing blog
Bring posts, images and URLs over from WordPress, Ghost, Hugo or another Astro theme.
Moving an existing blog is four jobs: posts, assets, taxonomy and URLs. Do them in that order — the last one only makes sense once the other three are stable.
1. Posts
Copy your Markdown (or exported HTML converted to Markdown) into
src/content/posts/. One file per post, filename becomes the URL slug.
Map the frontmatter:
| Your old field | inspos |
|---|---|
title |
title |
date / published_at |
date (ISO YYYY-MM-DD) |
excerpt / summary |
description |
cover / featured_image |
cover (path under public/) |
tags |
tags: [] |
category |
categories: [] |
draft: true |
keep it — drafts are excluded from the build output |
Anything else is ignored, so you can leave extra keys in place while you migrate.
# A quick sanity check: every post must parse before you build
npm run build2. Assets
Images belong in public/, referenced by absolute path: /img/hello.jpg.
If your old blog served wp-content/uploads/2024/05/photo.jpg, either keep that
path (copy the folder as-is into public/wp-content/uploads/...) so old links keep
working, or rewrite the references in one pass:
grep -rl 'wp-content/uploads' src/content/posts | while read f; do
sed -i 's#/wp-content/uploads/2024/05/#/img/#g' "$f"
done3. Categories and tags
Posts declare them in frontmatter; pages are generated from that data, so there is nothing to register:
categories: ['Tech']
tags: ['cloudflare', 'self-hosting']Category covers and blurbs are optional. Add them to src/data/taxonomy.ts when you
want a specific image instead of the first post’s cover:
export const categoryMeta = {
Tech: { cover: '/img/tech.jpg', description: 'Infrastructure and tooling.' },
};4. URLs
Three things decide whether old links survive:
trailingSlash: 'always'inastro.config.mjs— links are/posts/hello/, not/posts/hello.- The file name in
src/content/posts/—hello.mdbecomes/posts/hello/. - Redirects for anything that moved. On Cloudflare Pages put a
_redirectsfile inpublic/:
/2024/05/old-post/ /posts/old-post/ 301
/feed/ /rss.xml 301Vercel and Netlify use the same file format.
Keep a list of your ten most-linked URLs and check them by hand after the first deploy — that is where 404 traffic comes from.
5. Checklist before you switch DNS
-
npm run buildpasses (it runsastro checkfirst) -
dist/sitemap-index.xmllists every post -
site.config.yamlhas the real domain and language list - One post per language opens, with the language switch only where a counterpart exists
- Old URLs either still resolve or 301 to their new home
- Search finds an old post’s title (the index is built at deploy time)