How to keep versioned docs from cannibalizing search results

Versioned docs are good for readers on old releases and bad for search unless you are deliberate. /docs/1.4/install, /docs/2.0/install and /docs/install are three pages with the same title, nearly the same text and the same target query. Search engines pick one, and it is frequently the old one because it has had more time to collect links.

What cannibalization looks like

• Searching your product's name plus a feature returns a page from a version you no longer support.
• Your analytics show traffic to /docs/1.x/ pages that then bounce to the current docs.
• The current page ranks below the old one for its own title.
• Support tickets quote instructions from an old version.

The setup that prevents it

1. Canonical tags point old versions at the current page when the content is equivalent, or at themselves when the version genuinely differs. Pick one strategy per page type and apply it consistently. PathIntact flags canonicals that point at a different version so you can see the pattern.
2. Only the current version is in the sitemap. Old versions can stay online for readers, but listing them in the sitemap invites indexing. PathIntact reports sitemap entries that are marked noindex and pages that are indexable but missing from the sitemap, so the two stay in sync.
3. noindex on versions you do not want ranked, typically anything past end of life. Readers with a direct link still get the page.
4. Version switcher links live in navigation, not in body text. Body links from the current version into an old version tell search engines the old page is important. PathIntact's old-version-link rule reports body links from the latest version into older paths and ignores navigation and version switchers.
5. Titles include the version only where it helps. "Install (v1.4)" versus "Install" is a real difference; two pages titled "Install" are duplicate titles, which PathIntact also reports.
6. Retire versions with redirects, not deletions. When a version is removed, redirect its pages to the same path in the nearest supported version, or to the current version when the page no longer exists. Deleting creates hundreds of 404s at once; the sitemap diff tool shows exactly which URLs disappeared and whether they redirect.

Platform notes

• Docusaurus versions live under /docs/<version>/ with the current version at /docs/ and next for unreleased changes. TODO(verify): canonical behaviour across versions in the default theme.
• MkDocs with mike deploys each version to its own directory with a latest alias; canonicals are up to you or a plugin. TODO(verify)
• ReadMe serves versions with a version prefix and manages canonicals in the platform. TODO(verify): default canonical for older versions.
• Read the Docs (Sphinx) uses /<lang>/<version>/ and supports a default version and canonical URL setting. TODO(verify)

Keep it that way

Versioning problems come back with every release: a new version is forked from the old one, copying its links and canonicals. Monitoring the docs root with PathIntact detects the versioning pattern automatically and re-checks old-version links, cross-version canonicals, sitemap membership and duplicate titles on every crawl.

Check my docs