Docusaurus search results lead to an old docs version
Trace stale Docusaurus search results to the default documentation route, version snapshots, navigation, and version-specific indexing settings.
By Crawlito · 5 min read
In short
- The current development docs and the latest default version can be different in Docusaurus.
- lastVersion selects the default documentation version, while version paths determine the public URLs.
- Older supported docs can remain useful when their version and links are explicit.
On this page
- Identify the version behind each public address
- Read the configuration beside the actual release records
- Give readers and crawlers legible version choices
- Verify stable, next, and an older supported release
- Follow a release announcement back to the matching manual
- Frequently asked questions
- Inspect a stable documentation URL
If search sends users to an old Docusaurus guide, check which version the public default route serves, which version your navigation promotes, and what version the visitor actually needs. Docusaurus distinguishes the current development docs, version snapshots, and the latest version used for the default route. Correct the routing or navigation that is wrong and keep useful old instructions identifiable. Docusaurus versioning documentation
Identify the version behind each public address
Start with a command or setting that genuinely differs between releases. A setup step renamed between two major versions is a better marker than a shared introductory paragraph. Open the reported search result, the main Docs link, the version selector, and a direct bookmark for the supported older version. Record the final route, visible version label, and which command the page actually teaches.
In a common Docusaurus layout, docs/ contains the current working documentation and snapshots live under versioned_docs/. The public default can point at a snapshot of the latest released version while the development copy appears under a next-version route. The exact paths are configurable. A contributor editing a file under docs/ can therefore publish a successful build without changing the public default guide they were trying to correct.
Check which part of the experience someone means by “search.” Google or another external engine follows public pages according to its own systems. A site-search integration can be backed by a separate index with its own version filters and update schedule. Reproduce the failure in the relevant place. A fix to the public navigation can help external discovery but cannot necessarily correct a site search that selects records from an unrelated index.
Read the configuration beside the actual release records
Find the docs plugin or preset configuration that owns the affected route, especially if the site has separate guides for multiple products. Review the version list, the default version, and any explicit paths or labels. lastVersion selects which version is treated as latest for the default docs route. The value current explicitly selects the active development docs when that is your publication's release model. Docusaurus docs plugin reference
A team maintaining a released product should decide which instructions a first-time installer should receive today. A pre-release feature branch might contain accurate instructions for the next command-line tool while remaining unsuitable for a customer who uses the stable package. Get the release owner's answer before pointing the default at current. Conversely, a team that continuously ships the current docs may be inadvertently serving a historical snapshot at the default route.
Make a table with a row for stable, next, and each version still supported. Include source directory, public path on the deployed host, version label, and the target of the top-level navigation. A wrong path, a wrong label, and outdated content are three different bugs. If the label is correct but every example uses the old command, examine the snapshot content or a shared include before changing the route.
Give readers and crawlers legible version choices
Add visible version information where it helps someone decide whether to follow the steps. Link an older guide to the equivalent current task when such a guide exists. A general home link is less helpful to a reader who landed on one very specific error message. Preserve old versioned deep links for customers still using the supported release. The documentation site guide outlines how to keep command examples attached to their prerequisites.
Inspect the generated HTML for a stale navigation target. A hardcoded /docs/1.0/install in the homepage, footer, or a heavily used tutorial can keep pointing new readers to an obsolete installation path even though the top-level docs route is correct. Change links intended for new installations to the stable destination. Keep links from an archived release note pinned to the matching historical manual when the distinction matters.
For versions your organization intentionally wants excluded from external search, the docs plugin documents a version-specific noIndex setting. Verify the generated directive on that version and on stable. This is a broad editorial decision about discoverability. When the old manual still serves real users through search, visible labels and clear routing may be exactly what those users need. The index directive guide describes how to check the effect at the URL level.
Verify stable, next, and an older supported release
Use a small route matrix after every docs release. Open each version directly, follow its install or upgrade link, check the visible command, and use the version selector to reach the corresponding task in another release. Some guides have moved or changed names. A selector that silently sends readers from a specialized migration step to the homepage leaves them without context even when the destination status is successful.
| Starting point | What should establish success |
|---|---|
| Main product website | A new installer reaches a guide compatible with the supported stable release |
| Pre-release documentation | The page clearly identifies the upcoming version and its prerequisites |
| Old bookmarked route | A supported user gets the old command or an explicit task-level successor |
| External search result | Its final page describes the version, and offers a route forward where appropriate |
Inspect each intended public page's canonical and any robots directive, then compare with the sitewide sitemap. Canonicalizing old guides with genuinely different commands to a new guide can misrepresent the content relationship. The guide to canonical URLs explains what such a declaration communicates. If your own search integration is responsible, check a sample index record for the version, URL, and update time associated with the bad result.
Follow a release announcement back to the matching manual
Pick a public release note that mentions a feature introduced in a particular version. Follow its documentation link before and after changing the default. If the note describes an API that was later removed, a link that always follows the default can eventually take a reader to instructions for a different interface. A historical reference may need a pinned version URL even while the product homepage should follow the stable default.
Test the reverse journey too. From the old manual, look for a path to the release or migration instructions relevant to its version. A blanket “see latest” link can land on a new command with different arguments and no explanation of how to upgrade. A contextual link to the migration task lets a reader make that decision. Include this release-note route in your sample alongside the install page. It catches a navigation regression that a homepage-only test cannot show.
Frequently asked questions
Does editing the current docs always update the default page?
No. With a versioned site the public default may be a released snapshot. Check the source that builds the exact route you inspected.
Should every past version be removed from search?
Base that decision on support and user needs. Some readers need version-specific documentation precisely because the newer commands will fail on their installation.
Can I fix this with only a version banner?
A banner can prevent readers from following the wrong instructions. If the default route or a prominent link is wrong, repair that route or link too.
Inspect a stable documentation URL
Use the free page check on the public stable guide. Compare its content, indexing directives, and navigation with a guide from the older version that appeared in the result.
Filed under Platform guides. Topics: docusaurus, documentation, canonical, indexing