[akira28]

The API Explorer now lists topic pages under a Topics sidebar heading, above the endpoint groups. The heading shows a product's children: pages first, then a page for each entry of the OpenAPI x-topics extension that no child page covers. bump.sh topic URLs such as /topic/topic-rate-limiting stop returning 404.

Affects: API reference, Configuration

Prompt summary: Fix elastic/docs-eng-team#820 and the docs-builder side of elastic/docs-eng-team#1104. The first decision in elastic/docs-eng-team#820 was to prefer x-topics and fall back to children:. After review, the team inverted it: the two sources are combined with priority to children: pages, and x-topics is deprecated, with the migration after GA. children: pages also carry pages such as the Elasticsearch API conventions in elastic/docs-eng-team#1135.

Why

Nothing parses x-topics, so the Kibana, Kibana serverless, and Elastic Cloud topic pages that bump.sh serves have no native page. Cloud Billing has no securitySchemes, so its /authentication page is not generated either: bump.sh builds it from an x-topics entry titled Authentication. The sitemap parity test reports these as 8 of the 14 missing pages in elastic/docs-eng-team#1104.

What

Topics sidebar heading

Topic pages sit under a Topics heading, in both the default and the preview navigation. The heading only appears when a product has at least one topic page. The breadcrumb folds it into the spec crumb, like an x-tagGroups heading.

children: pages first, then x-topics

The Topics heading lists the children: pages in the declared order, then the spec's topics. A child page covers a topic when its first heading matches the topic title or its text matches the topic content. A covered topic gets no page, so Kibana lists kibana-api-overview and builds no Kibana spaces topic page. The build writes no redirect pages for topics. elastic/docs-infra#493 redirects the bump.sh topic URLs, such as /topic/topic-kibana-spaces to kibana-api-overview. The child page keeps the replaced topic URLs as page names, so the version switcher still matches it with the topic page in a version that builds one.

x-topics pages

Each topic that no child covers renders at /topic/topic-<slug>, the same URL as on bump.sh. When two entries produce the same URL, the first one wins and the build logs a warning. Authentication comes first and Rate limiting second, and the other topics follow alphabetically. The pinned titles are one list, TopicsNavigationItem.PinnedTitles. topic joins the reserved slugs for children: files.

Authentication topic

A topic titled Authentication does not get its own topic page. Its content opens the /authentication page, above the security schemes, and that page is listed under Topics. elastic/docs-infra#493 redirects /topic/topic-authentication there, as on bump.sh. This also works for a spec without security schemes, which fixes cloud-billing/authentication.

Types is a heading, after a divider

Topics and Types are both page-less groups, so they share one sidebar heading type that points at the product overview. Types used to be a folder that linked to its first schema page; it now only expands. A divider sets Types apart from the endpoint groups, as one already does for Topics. Type page breadcrumbs lose the Types crumb, which linked to that first schema page.

Sitemap parity test

The test now mirrors the exact page redirects from elastic/docs-infra#493 and elastic/docs-infra#494. They cover the /servers pages, the renamed Cloud Billing budgets group, the topic URLs this PR builds no page for, and the Streams operations Kibana removed from its 9.6 spec. With this PR and both redirect PRs, every production API sitemap page resolves. Those redirects apply on staging and edge only, until the cutover.

Out of scope: Expanding the Topics heading by default is in #4629, on top of this PR. Moving x-topics content to children: pages is tracked in elastic/docs-eng-team#1144, after GA. Elasticsearch topic pages are tracked in elastic/docs-eng-team#1143 and elastic/docs-eng-team#1135. The landing page still does not show its topic list, as before.

Verify

dotnet test tests/Elastic.ApiExplorer.Tests/
# TopicPageTests — parsing, URLs, order, nav placement, children and topics union, Authentication merge, generated pages

To check the sitemap parity against a staging build:

dotnet run --project src/tooling/docs-builder -- assembler build --environment staging --no-assume-build
FEATURE_ASSEMBLER_API_EXPLORER=true dotnet run --project tests/Elastic.Documentation.Build.Tests/ -- --treenode-filter '/*/*/ApiSitemapParityTests/*'

Check on the preview

• Kibana: Spaces — the children: page, listed first under Topics. The spec's Kibana spaces topic gets no page.
• Kibana Serverless: Kibana spaces — no children: page covers the topic, so the x-topics page renders.
• Cloud: Principles — topic page, with the Topics heading listing Authentication, Rate limiting, and Principles.
• Cloud Billing: Authentication — built from the Authentication topic alone, because the spec has no security schemes.
• Cloud: Authentication — the topic text above the apiKey scheme.
• Elasticsearch — control page: no x-topics and no children:, so no Topics heading.

[Mpdreamz]

I'm hoping to migrate these to regular markdown pages instead.

[github-actions]

Docs preview (local build)

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

Sample changed pages:

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

[akira28]

@Mpdreamz agreed, and this PR now follows that direction. We inverted the decision in elastic/docs-eng-team#820: children: pages take priority, and x-topics is deprecated.

• The Topics heading lists the children: pages first, in the declared order, then the spec's x-topics.
• A child page replaces a topic when its first heading matches the topic title or its text matches the topic content. The topic gets no page, and elastic/docs-infra#493 redirects its bump.sh URL to the child, so kibana/topic/topic-kibana-spaces forwards to kibana-api-overview.
• Topics that no child covers still render, so the bump.sh URLs for Kibana serverless, Elastic Cloud, and Cloud Billing keep working until we move them.
• We migrate the remaining x-topics content to children: pages after GA, in elastic/docs-eng-team#1144. Then x-topics support goes away.

The change is in 6b6d3bf, and 037490b leaves the redirects to docs-infra.