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

---

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

A new navigation-v2.yml file drives the sidebar, separate from navigation.yml. It supports five item types:

Key	Behaviour
label:	Non-clickable section heading; always expanded at any depth
toc:	Wires in a real TOC root (same as V1, no path_prefix: required)
page:	Cross-link to a specific .md file; renders as a real clickable link
group:	Placeholder folder — expand/collapse chevron, greyed link → stub page
title:	Placeholder leaf — greyed link → stub page

The current navigation-v2.yml contains the full proposed IA skeleton translated from the card-sort design. page: and toc: refs are used where content already exists; group: and title: placeholders mark items still to be wired up.

---

Placeholder stub pages

Every title: leaf and group: folder that lacks a page: now gets a generated stub page at /{sitePrefix}/_placeholder/{hash}/. The stub renders the full site chrome (header, V2 nav sidebar, footer) with an <h1> of the placeholder title and a "This content is coming soon." paragraph.

This means all placeholder nav items are greyed but clickable — clicking them navigates to the stub instead of doing nothing.

---

Filling the gaps

To wire up a placeholder:

• Replace title: Foo with toc: repo://path (optionally keeping title: Foo to override the root's own nav title) when a whole TOC root covers the topic.
• Replace title: Foo with page: docs-content://path/to/file.md (optionally keeping title: Foo to override the page's own nav title) when a specific existing page covers the topic. The URL is resolved automatically from the file path.
• Replace group: Foo with toc: when the folder gains a real root, or keep it as group: with page:/toc: children if the folder itself has no canonical URL.

In other words, title: doubles as a display name override — you never have to remove it when promoting a placeholder to a real link.

---

Sidebar behaviour

• Labels (any depth): always expanded, no toggle, no chevron
• group: nodes: expand/collapse toggle; accordion at top level (open one → siblings collapse); 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

Visual hierarchy

Level	Style
Level-1 label	text-xs font-semibold uppercase tracking-widest · full ink · thin horizontal rule above
Level-2+ label	same small-caps · 65% opacity
TOC / group / page link	sentence-case, normal weight, clickable (or greyed for placeholders)

---

URL scheme — known limitation and future direction

toc: entries currently use the same URL paths as V1 (navigation.yml), because the file-writing pipeline (GlobalNavigationPathProvider) derives output paths from NavigationTocMappings, which is populated from navigation.yml before SiteNavigationV2 is constructed. Changes to path prefixes in the navigation model do not propagate back to where HTML files are physically written.

The intended final scheme is deterministic and URI-derived: {scheme}/{host}/{path} for non-docs-content repos, and {host}/{path} for docs-content (the default narrative repo, so the scheme adds no disambiguation value). Making this work end-to-end requires wiring the V2 nav file into AssembleSources.AssembleAsync so that NavigationTocMappings is populated from navigation-v2.yml instead of navigation.yml. That work is out of scope for this prototype PR.

🤖 Generated with Claude Code

[github-actions]

🔍 Preview links for changed docs

• nav-v2-status.md