Nav sections: independent sidebar islands and dynamic top bar

[theletterf]

Summary

• Adds section: and island: item types in navigation-v2.yml that create independent nav trees ("nav islands"). Each section owns its own sidebar HTML — pages in one section never include another section's nav links in the DOM.
• The secondary nav bar is now data-driven from the nav-v2 file instead of hardcoded. Sections appear as left-aligned, compact tabs (55px bar height). Isolated sections (isolated: true) do not appear in the top bar.
• Per-section sidebar caching in GlobalNavigationHtmlWriter replaces the single "nav-v2" blob — each section's sidebar is rendered and cached independently.
• External URLs in section url: fields open in a new tab with a ↗ indicator to signal users they're leaving elastic.co/docs.
• Nav islands (island: item type) are intra-section subtrees that get their own focused sidebar when entered, with a back arrow pointing to the parent section. Island detection uses toc root identity (nav ownership model), not URL matching, so it works across all path prefixes.
• Section root pages skip current-page highlighting in the sidebar and auto-expand top-level folders for discoverability.
• The back arrow for top-level isolated sections is intentionally not implemented — the UX for exiting a top-level island is still under design review.

Tab ordering

Tabs follow a task-flow logic — building tabs grouped together, situational tabs at the end:

Guides | APIs ↗ | Reference | Troubleshoot | Release notes

Sections (top bar tabs)

Section	Preview URL
Guides (full V2 tree)	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/
APIs	https://www.elastic.co/docs/api (external, opens in new tab)
Reference	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/reference/
Troubleshoot	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/troubleshoot/
Release notes	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/release-notes/

Isolated sections (not in top bar)

Section	Preview URL
Extension points	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/extend/

Nav islands (intra-section, with back arrow)

Island	Parent	Preview URL
Account and preferences	Guides	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3133/cloud-account

Note: Logstash plugins and versioned plugins islands are configured but use logstash-docs-md (a private repo), so they are not accessible in PR previews. Test locally with dotnet run --project src/tooling/docs-builder -- assembler build && dotnet run --project src/tooling/docs-builder -- assembler serve → http://localhost:4000/docs/reference/logstash/plugins/

YAML format

nav:
  - section: Guides            # top bar tab, owns full sidebar
    url: /
    children:
      - label: Elasticsearch fundamentals
        children: [...]
      - island: Account and preferences   # focused sidebar + back arrow
        toc: docs-content://cloud-account

  - section: APIs              # external link, new tab with ↗
    url: https://www.elastic.co/docs/api

  - section: Reference         # top bar tab, own sidebar
    url: /reference/
    children:
      - toc: docs-content://reference
      - island: Logstash plugins          # focused sidebar + back arrow
        toc: logstash-docs-md://lsr

  - section: Troubleshoot      # top bar tab, own sidebar
    url: /troubleshoot/
    children:
      - toc: docs-content://troubleshoot

  - section: Release notes     # top bar tab, own sidebar
    url: /release-notes/
    children:
      - toc: docs-content://release-notes/intro

  - section: Extension points  # isolated: not in top bar
    url: /extend/
    isolated: true
    children:
      - toc: docs-content://extend

🤖 Generated with Claude Code

[KOTungseth]

Now that Docs, Release notes, Troubleshoot, API reference, and Reference are grouped together, we need to find a solution for the Docs label.

Release notes, Troubleshoot, API reference, and Reference are content types and help users navigate to a specific kind of documentation. Docs is not a content type, but is the parent context to everything else that lives inside of Docs. By grouping Docs, Release notes, Troubleshoot, API reference, and Reference together, we have mixed together wayfinding and content-type navigation.

The cleanest fix right now is to handle the "back to landing page" behavior through a separate, persistent element, like a logo or a breadcrumb. That way, the secondary nav becomes a coherent, single-purpose set of content-type links and the navigation to the landing page exists independently.

We could also change the Docs label. Something like Home or Overview signals intent a bit more clearly than Docs, through is still doesn't fully resolve the category mismatch.

[KOTungseth]

The API reference link creates a classic navigation trap. When users enter the Bump.sh site, they lose their wayfinding back to our elastic.co/docs canonical site.

Some options:

• Open the API reference docs site in a new tab to allows users to keep the Elastic Docs tab and return to it naturally.
• Label the API reference link with a API reference ↗ visual treatment to clearly set user expectations that when they click the link, they'll be leaving elastic.co/docs.
• Negotiate a Back to Elastic Docs link with Bump.sh that easily points users back to elastic.co/docs.

[theletterf]

I would go for

Negotiate a Back to Elastic Docs link with Bump.sh that easily points users back to elastic.co/docs.

Can we add it?

[florent-leborgne]

A combination of all of these 3 options would be best

[Mpdreamz]

API reference ↗ and opening in new tab has my vote, until we have a clear vision of whats going to ship first API Explorer or v2.

[theletterf]

Implemented! I've also renamed and reordered items. WDYT?

More options:

• Get started
• Learn
• Handbook
• Home

[theletterf]

@Mpdreamz Right now we have islands: as navs that have a parent in a current nav but lead to a separate nav, and sections that have isolated: true and are effectively parentless. I feel something is not quite elegant with this solution...