Prototype nav-v2: new IA with label sections, accordion sidebar

[theletterf]

Prototypes a new information architecture sidebar gated behind the nav-v2 feature flag (auto-enabled in dev and preview environments). Content is served at the same URL paths as V1 — only the sidebar layout changes.

Demo: https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2927/get-started

Contributes to: https://github.com/elastic/docs-content-internal/issues/1015

---

What's included

This branch now incorporates the work from PR #3133 (nav-v2-sections, merged into nav-v2), which adds independent sidebar islands and a dynamic data-driven top bar on top of the base nav-v2 prototype.

From this PR (nav-v2 base)

• New navigation-v2.yml file drives the sidebar, separate from navigation.yml.
• Five item types: label:, toc:, page:, group:, title:.
• Placeholder stub pages — every title: leaf and group: folder without a page: gets a generated stub at /{sitePrefix}/_placeholder/{hash}/.
• Accordion sidebar behaviour, visual hierarchy, and expand/collapse logic.

From PR #3133 (nav-v2-sections, merged)

• section: item type: each section owns its own sidebar HTML — pages in one section never include another section's nav links in the DOM.
• island: item type: intra-section subtrees that get their own focused sidebar when entered, with a back arrow pointing to the nearest ancestor page. Island detection uses toc root identity, not URL matching.
• Dynamic secondary nav bar: data-driven from the nav-v2 file instead of hardcoded. Sections appear as left-aligned compact tabs. Isolated sections (isolated: true) do not appear in the top bar.
• Per-section sidebar caching in GlobalNavigationHtmlWriter — each section's sidebar is rendered and cached independently.
• External URLs in section url: fields open in a new tab with a ↗ indicator.
• Section root pages skip current-page highlighting and auto-expand top-level folders for discoverability.

Tab ordering

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/2927/
APIs	https://www.elastic.co/docs/api (external, opens in new tab)
Reference	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2927/reference/
Troubleshoot	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2927/troubleshoot/
Release notes	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2927/release-notes/

Isolated sections (not in top bar)

Section	Preview URL
Extension points	https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2927/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/2927/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/

---

Navigation YAML format (config/navigation-v2.yml)

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/security
      - 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

The remaining item types (label:, toc:, page:, group:, title:) behave as documented below.

---

Placeholder stub pages

Every title: leaf and group: folder that lacks a page: gets a generated stub page at /{sitePrefix}/_placeholder/{hash}/. The stub renders the full site chrome with an <h1> of the placeholder title and a "This content is coming soon." paragraph. All placeholder nav items are greyed but clickable.

---

Filling the gaps

• Replace title: Foo with toc: repo://path when a whole TOC root covers the topic.
• Replace title: Foo with page: docs-content://path/to/file.md when a specific existing page covers the topic.
• Replace group: Foo with toc: when the folder gains a real root, or keep it as group: with children if the folder itself has no canonical URL.

---

Sidebar behaviour

• Labels (any depth): always expanded, no toggle, no chevron.
• group: nodes: expand/collapse toggle; accordion at top level; greyed link → stub page.
• toc: nodes: full live tree, same expand/collapse as V1.
• page: leaves: clickable link to the canonical page URL.
• title: leaves: greyed link → stub page.

---

URL scheme — known limitation and future direction

toc: entries currently use the same URL paths as V1 (navigation.yml), because the file-writing pipeline derives output paths from NavigationTocMappings, which is populated from navigation.yml before SiteNavigationV2 is constructed. The intended final scheme ({scheme}/{host}/{path}) requires wiring the V2 nav file into AssembleSources.AssembleAsync. That work is out of scope for this PR.

🤖 Generated with Claude Code

[github-actions]

🔍 Preview links for changed docs

• nav-v2-status.md

[theletterf]

Added a temporary workaround for duplicate Nav V2 page entries.

Some pages intentionally appear in more than one sidebar location while the IA is still being validated. Instead of removing those duplicates now, the sidebar now assigns each rendered nav link a stable data-nav-v2-location, remembers the location the user clicked for that page in sessionStorage, and focuses only that selected occurrence after navigation. Direct loads, organic search, shared URLs, and reloads still use the same canonical page URL and fall back to the first stable nav occurrence, with the existing deeper same-branch behavior preserved for folder/index duplicates.

This keeps one page URL and avoids duplicate search results, while preventing multiple duplicate sidebar entries from being highlighted or expanded at the same time. We can remove or explicitly canonicalize duplicate nav entries later as a separate IA decision.