Prompt
How do I move content from a legacy CMS to a headless CMS without breaking links?
Latest observation
Migrating content from a legacy CMS to a headless CMS without breaking links comes down to one principle:
Preserve or map every old URL to a stable new URL, and keep redirects in place long enough for search engines and users to catch up.
Here’s a practical way to do it.
1) Inventory all current URLs
Before migrating, export a list of everything that’s publicly accessible:
- pages
- posts/articles
- media files
- categories/tags
- PDFs and other downloads
- any canonical or vanity URLs
- old query-based URLs if they’re in use
You want a full URL map, not just the content itself.
2) Decide your new URL structure early
Pick a URL pattern for the headless CMS and frontend, for example:
/blog/my-article/docs/getting-started/products/widget-a
Try to make it:
- human-readable
- stable over time
- consistent across content types
The biggest risk is changing the path structure too many times during migration.
3) Create a URL mapping table
Build a spreadsheet or migration table with columns like:
- legacy URL
- new URL
- content ID
- content type
- redirect status
- notes
Example:
| Legacy URL | New URL | Redirect |
|---|---|---|
/old-blog/how-to-x | /blog/how-to-x | 301 |
/cms/page?id=123 | /about/company | 301 |
/files/guide.pdf | /assets/guide.pdf | 301 |
This becomes the source of truth for redirects.
4) Keep stable identifiers for content
In the headless CMS, assign each piece of content a persistent ID/slug.
Best practices:
- use a unique internal ID separate from the slug
- avoid regenerating slugs unless absolutely necessary
- store the legacy URL as metadata
- preserve published dates and canonical fields if relevant
This helps you maintain references across migrations and future updates.
5) Rewrite internal links during migration
A lot of broken-link problems come from content bodies, not just top-level pages.
When importing content:
- parse HTML/Markdown fields
- convert old internal links to new URLs
- update image src paths to the new asset location
- update embedded documents and downloads
- check anchor links within pages
For example:
- old:
<a href="/cms/page?id=123"> - new:
<a href="/about/company">
If possible, do this automatically with a link-rewriting script.
6) Use 301 redirects for every old URL
Set up permanent 301 redirects from old URLs to new ones.
This is critical for:
- SEO
- bookmarks
- external backlinks
- users with saved links
- old emails/newsletters
Avoid:
- 302 redirects unless temporary
- redirect chains
- redirect loops
Best practice:
- redirect old content URLs directly to the final destination
- do not redirect to a generic homepage unless there is no equivalent page
7) Preserve media and asset URLs carefully
Images, PDFs, and other files often break first.
Options:
- keep the same file paths if possible
- or create redirects for old asset URLs
- or migrate assets to a new CDN/storage bucket and map old paths
For media embedded in content:
- update all source references
- verify hotlinked assets
- ensure file permissions/CDN rules are correct
8) Handle canonical tags and metadata
To avoid SEO confusion:
- set canonical URLs on the new site
- make sure they point to the new destination
- preserve metadata where relevant:
- titles
- meta descriptions
- Open Graph tags
- structured data
- hreflang if multilingual
If a page exists in both old and new systems during transition, canonical should point to only one version.
9) Test before launch
Run a staging migration and validate:
- all old URLs return 301 to the correct new URL
- all internal links work
- no 404s in page content
- assets load correctly
- forms, downloads, embeds, and scripts still work
- no redirect chains longer than one hop
Use tools like:
- Screaming Frog
- Sitebulb
- custom crawl scripts
- server logs
10) Monitor after launch
After going live:
- check 404 logs regularly
- monitor Search Console / webmaster tools
- track redirect hits
- fix missed mappings quickly
- update sitemap.xml and submit it to search engines
Keep redirects live for a long time—often at least 12 months, and longer if the site has strong SEO value or backlinks.
Recommended migration approach
A good migration usually looks like this:
- Export content and URLs from legacy CMS
- Define new content model and URL patterns
- Import content into headless CMS
- Rewrite internal links and media references
- Publish frontend with canonical URLs
- Set up 301 redirects from every old URL
- Test extensively
- Monitor and fix edge cases
Common mistakes to avoid
- changing slugs during import without redirect mapping
- forgetting media and PDF URLs
- relying only on homepage redirects
- using temporary redirects
- not updating internal links in content body
- launching without crawl testing
- removing redirects too soon
If you want a safe fallback
If your legacy CMS already has lots of inbound links and SEO value, consider:
- keeping the old URL paths where possible
- using reverse proxy rules so old paths still resolve
- migrating in phases instead of all at once
If you want, I can also give you:
- a migration checklist,
- a URL mapping spreadsheet template, or
- an example redirect rule set for Nginx/Apache/Next.js/Vercel.