[reakaleek]

The API version picker now opens the same page in the other version when that version has it, such as the same operation. Before, it always opened the version's landing page.

Affects: API reference, Site UI

Prompt summary: Implement elastic/docs-eng-team#1081. Choosing another version on an API page should keep the reader on the same operation if it exists there, as Bump.sh does. Version and API switches should behave like htmx links.

Why

The picker only knew the root URL of each version, so every page linked to the same landing pages. A reader on an operation lost their place after a version switch. The issue reporter calls this a blocker for their API.

Closes elastic/docs-eng-team#1081

What

Same-page links

Each version now records which pages it renders. A page links to the matching page in another version when that version has it. Otherwise it links to that version's landing page, as before. Collapsed operations count under their former URLs too.

Build order

The generator builds every version's navigation before any page renders, because a page must know what the other versions contain. Total work is the same. Build time did not change in a local run on docs/ (about 23 to 27 seconds for both, three runs each, inside run-to-run noise).

Pickers and htmx

The version picker, the API product switcher and the All APIs link are normal boosted links, so switching does not reload the page. Within one API, boosted navigation swaps only the content grid, and the pickers sit outside it. A small script copies the new version links from each response, so the picker follows the page the reader is on. A move to another version or product swaps the whole main container instead, so the navigation tree and the context bar follow. The isolated header is preserved across swaps, so the script also copies its title. Only a move between a docs page and an API page still reloads, because the site header differs.

Verify

dotnet test tests/Elastic.ApiExplorer.Tests/
cd src/Elastic.Documentation.Site && npm run test
dotnet run --project src/tooling/docs-builder -- serve

Open /api/doc/elasticsearch/operation/operation-search-application-get-behavioral-analytics and pick v9. The page stays on the same operation. On an operation that exists only in main, picking v8 opens the v8 landing page.

Check on the preview

• Elasticsearch: Get behavioral analytics - the issue's page. Pick v9 and v8 in the version picker: each opens the same operation.
• Elasticsearch: Cancel reindex - exists in main and v9 only. Pick v8: it opens the v8 landing page.
• Elasticsearch: landing page - control page: the picker still opens each version's landing page.

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4542/

Sample changed pages:

• docs/data/openapi/api-explorer.md