[Mpdreamz]

A section: APIs with floating: api in navigation.yml now mounts every declared API in the assembler navigation tree, so the sitemap walk and the llms.txt listing read the APIs from the tree like any other page. A build that does not render the API Explorer is unchanged.

Affects: Assembler builds, Navigation, Content export

Prompt summary: Make API pages part of the navigation tree in isolated and assembler builds, because the sitemap and llms.txt read that tree and the API pages were a side door next to it. The roots must exist when the navigation is built, with the details filled in later. This is the fourth step of the design in RFC: Floating sections in the navigation tree, and it implements the acceptance criteria of docs-eng-team#825.

Why

The assembler renders API pages after the Markdown build and SiteNavigation never sees them. llms.txt has to append the API catalog by hand in GenerateApiSection, and the sitemap walk cannot reach the pages.

What

The APIs section

SiteNavigation mounts a section: that has floating: <kind> as a hub. Its children are the roots of every floating section of that kind the build offers, and its URL is the hub page of the kind, /docs/api. A section without any such sections keeps its other behaviour. The APIs tab of the navigation preview keeps its external: link either way. navigation.yml gets an APIs section, and the preview file gets floating: api on its existing tab.

Roots first, children later

AssemblerApiSections finds the repositories that declare APIs when the build starts, and offers one section per API in key order. Their roots exist when the navigation is built. AssemblerOpenApiBuildStep attaches a generator to each owner and fills the sections from the same trees it renders the pages from, so nothing is fetched or built twice. A root takes the spec title once the spec is read, as the API hub does. A failed API hides its root.

llms.txt and the sitemap

The llms.txt listing walks the tree, and GenerateApiSection is deleted. It still links the Markdown export of each API, as before, so its output does not change. The sitemap walk skips links to a heading inside a page. The /docs/api/ filter stays until docs-eng-team#725.

Reading order

The hub and the root of each API take a place in the navigation order, so the previous and next links would walk into them: the last page of the docs would point to the APIs, and in the preview navigation the Reference page would have the Logstash API as its previous page. The pager now skips the hub and every floating root, so paging through the docs does not change.

Docs

docs/documentation/assembler/navigation.md documents floating:.

Stack: 4 of 5, on top of #4731.

Out of scope: replacing the link check in #4653, attaching every declared API without a toc entry, publishing the assembler's APIs in links.json, and removing the sitemap filter. The assembler, serve and Codex builds still reject an api: entry in a docset toc.

Verify

mise run test
dotnet test --project tests/Navigation.Tests --treenode-filter "/*/*/FloatingHubNavigationTests/*"
dotnet test --project tests/Elastic.Documentation.Build.Tests --treenode-filter "/*/*/AssemblerOpenApiBuildStepIntegrationTests/*"

The integration test needs network access to CloudFront. It builds a docset with the Elasticsearch API, runs the assembler step, and checks the hub, the sitemap walk and the llms.txt listing.

🤖 Generated with Claude Code

[infra-vault-gh-plugin-prod]

Severity: P3 (Low)

For a floating APIs section without external:, the tab gets the hub URL but is still assigned SectionId: sectionNav.Id below. API pages and the catalog retain their own navigation roots, so that ID never matches; the header's URL-based active-state fallback also excludes links with a section ID. Consequently, the newly supported tab never becomes active on its own pages. Leave the section ID unset for floating hubs or otherwise associate the rendered API roots with the tab, and cover active-state matching in the test.

_{Generated by Libra. React with 👍 or 👎 to give feedback on this comment.}

[infra-vault-gh-plugin-prod]

Severity: P3 (Low)

This PR deletes every test in SitemapTests.cs and leaves only the license header. That removes all coverage of SitemapBuilder.Generate: XML output, ordering, the entry-count limit and the /docs/api/ exclusion. It also removes coverage of EsSitemapReader.BuildSearchBody, and nothing else in tests/ covers either one. The PR also changes the sitemap filter in this same PR (it now drops the /docs/api hub URL as well), and no test covers that change. The deletion looks accidental. Please restore the file and add a case for the exact /docs/api key.

_{Generated by Libra. Specialist: libra-complexity. React with 👍 or 👎 to give feedback on this comment.}

[github-actions]

Docs preview (local build)

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

Sample changed pages:

• docs/data/openapi/api-explorer.md
• docs/documentation/assembler/navigation.md