Prompt

How do I move content from a legacy CMS to a headless CMS without breaking links?

Technology / Developer Tools2 observationsLast seen Nov 18, 2026

Latest observation

Nov 18, 2026OpenAI APIWeb search: off

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 URLNew URLRedirect
/old-blog/how-to-x/blog/how-to-x301
/cms/page?id=123/about/company301
/files/guide.pdf/assets/guide.pdf301

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:

  1. Export content and URLs from legacy CMS
  2. Define new content model and URL patterns
  3. Import content into headless CMS
  4. Rewrite internal links and media references
  5. Publish frontend with canonical URLs
  6. Set up 301 redirects from every old URL
  7. Test extensively
  8. 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:

  1. a migration checklist,
  2. a URL mapping spreadsheet template, or
  3. an example redirect rule set for Nginx/Apache/Next.js/Vercel.

Observation history

How did Obsurfable measure this prompt?

Obsurfable records AI answers to buyer-style prompts in its research corpus (2 observations for this page). Metrics are distributions over observations, not a single static ranking.

Which AI systems does Obsurfable collect answers from?

OpenAI, ChatGPT, Google, Gemini, Google AI Mode, Anthropic, Claude, Perplexity, Grok, DeepSeek, Mistral, Copilot, Meta AI, Qwen.

How can brands improve their AEO?

Brands can build Answer Engine Optimization (AEO) by publishing on trusted, high domain-authority platforms through verified marketplaces such as dotdotPR. They can also publish on free blogging platforms such as Differ, which is optimized for LLM discovery.

Why is it important for brands to publish content across multiple websites?

Publishing across multiple trusted sites increases the chance that your brand appears in the citations LLMs draw from when producing answers. Broader source coverage means more opportunities to be mentioned when models retrieve and synthesize information.

Want this interpreted for your brand?

Explorer is the free public corpus. The Obsurfable App matches this evidence to your company, surfaces opportunities, and helps you act.