[Mpdreamz]

A docset that mounts an API now publishes its pages in links.json, and a cross-link such as elasticsearch://api/elasticsearch/8/operation/operation-search resolves to the page or fails the build when the page is missing in that version. Docsets that mount no API publish the same links.json as before.

Affects: Links & redirects, Authoring, API reference

Prompt summary: Make API pages part of the navigation tree in isolated and assembler builds, so links to them can be validated like any other cross-link. Keep the published form compact and every lookup O(1), however many API versions a section has. This is the third step of the design in RFC: Floating sections in the navigation tree.

Why

An API page is not a Markdown file, so it is not in links.json. An author cannot cross-link to one, and a hard-coded https://www.elastic.co/docs/api/doc/... link is not checked in an isolated build. One API can have several versions of thousands of pages, and the same page paths repeat in every version.

What

One entry per page, with its versions

RepositoryLinks gains an optional floating property, keyed by {kind}/{key}. For each API it lists every page path once with a bit mask of the versions that contain it. The property is left out when empty, so existing links.json files do not change.

Each version states its root

The section does not name a routing pattern. Each version carries its name, the root of its URLs, and whether it is hidden or current. A reader joins a root and a page path, and never adds a v segment or knows how the API routes. The API Explorer builds the roots with ApiUrlBuilder, the same code that routes the pages.

Aliases under their canonical page

The former per-operation paths of a collapsed operation are listed under the canonical path, per version, so the canonical path is written once however many aliases it has. The reader builds the reverse lookup once, so finding the canonical page of an alias stays one lookup.

The lookup

CrossLinkResolver splits api/{key}[/{version}]/{page}, finds the section by key, maps the version to its bit and tests the mask of the page. The version is the exact name of a version, such as 8 or main. A page of the current version with the same name wins over the version, so adding a version never changes where a link points. Without it, the link reaches the current version, and a section with no current version does not guess one. Every step is a hash lookup or a bit test, so the cost does not grow with the number of versions.

Resolving to a site path

API pages sit at the site root, outside every repository path_prefix. IUriEnvironmentResolver.ResolveSitePath builds the URL from the site root. An assembler build links to the page on the site it builds, and an isolated build links to the published page on https://www.elastic.co/docs/. Codex builds link to the published page too, and a #fragment stays on the URL unchecked.

Emission and docs

IFloatingSection.ToLinkSection builds the section from the same per-version page names the version switcher uses. The syntax is documented in docs/data/openapi/api-explorer.md.

Example

The excerpts come from a real build of docs/ with - api: elasticsearch in the toc, trimmed to a few entries. The aliases entry is made up: that build had no collapsed operations.

A docset that mounts an API gets one extra property in links.json. Everything else in the file is unchanged.

{
  "origin": { "...": "unchanged" },
  "url_path_prefix": "",
  "links": { "index.md": {}, "...": {} },
  "cross_links": [],
  "floating": {
    "api/elasticsearch": {
      "versions": [
        { "name": "8", "root": "api/doc/elasticsearch/v8", "hidden": true },
        { "name": "9", "root": "api/doc/elasticsearch/v9", "hidden": true },
        { "name": "main", "root": "api/doc/elasticsearch", "current": true }
      ],
      "pages": {
        "": 7,
        "authentication": 7,
        "operation/operation-search": 7,
        "operation/operation-cat-circuit-breaker": 6,
        "operation/operation-autoscaling-get-autoscaling-policy": 1
      },
      "aliases": {
        "8": {
          "operation/operation-search": ["operation/operation-search-1", "operation/operation-search-2"]
        }
      }
    }
  }
}

To rebuild a URL, join the root of a version and a page path. The landing page has the empty path, and its URL is the root. The position of a version in versions is its bit, so 8 is bit 0, 9 is bit 1 and main is bit 2. A mask says which versions contain the page:

Page	Mask	Bits	Exists in
operation/operation-search	7	111	8, 9, main
operation/operation-cat-circuit-breaker	6	110	9, main (added in 9.x)
operation/operation-autoscaling-get-autoscaling-policy	1	001	8 only (gone in newer versions)
"" (the landing page)	7	111	8, 9, main

8 and 9 are hidden, so they are reachable by link but out of the sitemap, and main is the visible, current version. In that build, 579 pages exist in every version, 44 only in 9 and main, and 11 only in 8, so 634 entries cover 1,902 page and version combinations. All 1,902 match the files the build rendered, found through the stated roots. A docset that mounts no API has no floating property at all.

Cross-links resolve against that section. These results come from running the real resolver on the real links.json of that build, with the repository name docs-builder:

Cross-link	Result
docs-builder://api/elasticsearch/operation/operation-search	https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search
docs-builder://api/elasticsearch/8/operation/operation-search	https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-search
docs-builder://api/elasticsearch/main/operation/operation-search	https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search
docs-builder://api/elasticsearch	https://www.elastic.co/docs/api/doc/elasticsearch
docs-builder://api/elasticsearch/operation/operation-search#responses	https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search#responses
docs-builder://api/elasticsearch/operation/operation-autoscaling-get-autoscaling-policy	error: 'operation/operation-autoscaling-get-autoscaling-policy' is not a page of 'api/elasticsearch' in the current version.
docs-builder://api/elasticsearch/8/operation/operation-cat-circuit-breaker	error: 'operation/operation-cat-circuit-breaker' is not a page of 'api/elasticsearch' in version '8'.
docs-builder://api/elasticsearch/v8/operation/operation-search	error: 'v8/operation/operation-search' is not a page of 'api/elasticsearch' in the current version. The version is named 8, and no reader guesses a v prefix.

Stack: 3 of 5, on top of #4718.

Out of scope: the assembler wiring, navigation.yml mounting, replacing the link check in #4653, and anchor checking. Only a docset that mounts an API with an api: toc entry publishes anything, and no docset does yet.

Verify

mise run test
dotnet test --project tests/Elastic.Markdown.Tests --treenode-filter "/*/*/FloatingLinkTests/*"
dotnet test --project tests/Elastic.ApiExplorer.Tests --treenode-filter "/*/*/OpenApiGeneratorMultiVersionTests/FloatingSection*"

🤖 Generated with Claude Code

[github-actions]

Docs preview (local build)

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

Sample changed pages:

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