How to migrate docs platforms without losing SEO

A docs migration is a URL migration. The content may be identical on the new platform, but if the paths change and nothing redirects, search engines see hundreds of 404s, inbound links from blog posts and Stack Overflow answers die, and the deep links your own product emits (error messages, CLI hints, emails) send users to dead pages. This checklist keeps that from happening.

Before the migration

1. Export the complete list of current URLs. Fetch the old sitemap (/sitemap.xml, including index files) and add anything the sitemap misses: pages found by crawling, URLs from your analytics with traffic in the last 12 months, and URLs referenced from your product. Keep this list; it becomes the baseline.
2. Record the anchors that matter. Section deep links (/page#section) are invisible to server-side redirects. List the fragments your product, changelog and support articles link to.
3. Decide the new URL scheme once. Trailing slash or not, .html or not, versioned prefix or not. Mixing forms creates duplicate content and redirect chains.
4. Map old paths to new paths. Most map one-to-one; the rest need a decision: merge into a new page, redirect to a parent, or retire with a real 410. The migration redirect checker does the mechanical part: it requests every old path on the new base and suggests targets for the ones that break.
5. Prepare redirects in the new platform's format. See the redirect rules cheat sheet. Prefer HTTP 301 redirects at the host over client-side redirect pages.

During cutover

6. Deploy redirects with the new site, not after. The first crawl by a search engine after cutover decides how much ranking transfers.
7. Keep the old sitemap reachable for a while, or submit the new one immediately. Search consoles pick up the new URLs faster when the sitemap is fresh and every entry returns 200.
8. Set canonicals on the new pages. Every page should canonicalize to itself on the new domain and path.
9. Preserve heading text where you can. Anchors are generated from headings on almost every platform; keeping the wording keeps the fragments alive. Where a heading must change, add an explicit id matching the old one if the platform allows it.

After cutover

10. Diff the sitemaps. The sitemap diff tool shows what was added and removed and status-checks every removed URL. Anything that 404s without a redirect is a lost link.
11. Crawl the new site for broken anchors and orphans. Pages that existed in the old navigation but were left out of the new one are reachable only from search, and they will drop out of it.
12. Watch it for weeks, not hours. Redirect rules get edited, pages get renamed again, and external references keep arriving. Upload your old URL list as a baseline in PathIntact and every URL that later returns 404 without a redirect is reported as a missing redirect, with a suggested target and a copyable rule.

Common mistakes

• Redirecting everything to the docs home page. It preserves traffic for a week and then loses it, because the pages no longer answer the query.
• Redirect chains: old platform → interim path → final path. Collapse them to a single hop.
• Forgetting versioned docs. /docs/1.x/ trees are often the most linked pages from old forum answers.
• Changing headings during the move. Fragment links break with no server-side signal at all.

Check the new site