Skip to content

Findability prototype (Alex): nav + hub + landing#3557

Draft
itsalexcm wants to merge 207 commits into
mainfrom
findability/alexcerezo
Draft

Findability prototype (Alex): nav + hub + landing#3557
itsalexcm wants to merge 207 commits into
mainfrom
findability/alexcerezo

Conversation

@itsalexcm

@itsalexcm itsalexcm commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Why

This draft is my owned iteration of the Findability prototypes so design and UX work can proceed on a single branch without depending on other authors' draft PRs. It stacks nav, hub pages, and the search-first landing for end-to-end review before deciding production merge order.

What

Built on findability/alexcerezo by merging, in order:

  • Nav V2 from local nav-v2 (#2927, includes #3133): sections, sidebar islands, accordion IA, dynamic top bar, placeholders
  • Hub pages from hub-pages (#3223): layout: hub, {hero} / {card-group} / {whats-new} directives, product hub routing; config/assembler.yml uses narrative.current: hub-pages for docs-content pairing
  • Landing from landing-page/prototype (#3250): search-first homepage prototype; docs/index.md sets layout: landing-page

Alex-specific deltas on top of those prototypes:

  • Nav V2 WIP: sidebar sticky chrome, _TocTreeNavV2 / search / TOC layout, isolated header flow, assembler nav HTML polish
  • Reconciled merges with main: applies-to snapshots, cli-modifiers / storybook directives, WEBSITE_SEARCH + NAV_V2 in assembler dev
  • Deferred: skills infobox and old-landing CTA follow-ups (feat/landing-page-skills-infobox, fix/landing-page-follow-ups) — they target the pre-prototype landing layout and need a follow-up on the new _LandingPage.cshtml

Reference prototypes (#3256 demo/findability) are inspiration, not blockers for this branch.

Test plan

  • Assembler preview: landing /, hub /products/elasticsearch/v9/, Nav V2 island (e.g. cloud-account), top-bar sections
  • Isolated serve with FEATURE_NAV_V2=true on :3000 for sidebar polish
  • Confirm hub markdown resolves via elastic/docs-content hub-pages branch in assembler build

Made with Cursor

theletterf and others added 30 commits March 20, 2026 09:37
@theletterf @claude
Prototype nav-v2: label sections, accordion sidebar, feature flag
d75da63 
Adds a new `navigation-v2.yml`-driven sidebar behind the `nav-v2`
feature flag (enabled by default in dev/preview environments).

- New YAML format: label sections (non-clickable headings), toc entries
  that resolve to existing navigation nodes at their original URL paths,
  page crosslinks, and title-only placeholder (disabled) links
- `SiteNavigationV2` extends `SiteNavigation`, passes the original
  nav file to the base constructor so content URLs are unchanged; builds
  a separate `V2NavigationItems` tree for sidebar rendering
- `GlobalNavigationHtmlWriter` detects `SiteNavigationV2` and returns
  the same full V2 nav HTML (cached once) for every page
- `_TocTreeNavV2.cshtml` renders labels as `<span>`, placeholders as
  `aria-disabled` anchors, folders/leaves same as V1
- `pages-nav-v2.ts` adds accordion collapse (open one section → others
  collapse) and current-page marking with no auto-expand
- Feature flag key normalisation: assembler.yml uses `NAV_V2` (underscore)
  but lookup uses `nav-v2` (hyphen); fixed by calling `featureFlags.Set`
  which normalises via `ToLowerInvariant().Replace('_', '-')`

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Fix accordion: unique IDs per label section
0f58ae0 
ShortId.Create("label") always produced the same SHA256 hash, so all
8 label checkboxes shared id="v2-label-1ACA80E8". Every <label for="">
targeted the first checkbox, making only "Get Started" expandable.

Fix: include the label text in the hash — ShortId.Create("label", label).

Also updates nav-v2-status.md to reflect verified accordion behaviour.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Rewrite navigation-v2.yml with proposed IA (6 top-level labels, neste…
407c477 
…d labels)

Translates the team's proposed information architecture into the V2 nav:

Top-level labels:
  • Elasticsearch fundamentals (get-started + placeholder concepts)
  • Install, deploy, and administer (deploy-manage + cloud-account)
  • The Elasticsearch Platform (container for nested labels)
  • Solutions and project types (solutions)
  • Reference (elasticsearch + kibana)
  • Troubleshooting (troubleshoot)

"The Elasticsearch Platform" has three nested labels:
  • Ingest and manage data → toc: manage-data
  • Search, visualize, and analyze → toc: explore-analyze
  • AI and machine learning → title: placeholders (content lives in
    explore-analyze today; dedicated toc roots needed to wire up)

Nested labels work with no code changes — the YAML parser, SiteNavigationV2
builder, and _TocTreeNavV2 partial already recurse through children at any
depth. The Razor partial applies level-aware styling (font-semibold at
level 0, lighter weight at depth 1+).

Also documents the proposed IA mapping and content split analysis
in nav-v2-status.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Labels always expanded with no toggle; only TOC folders toggle
76657fb 
Labels at any depth are now unconditionally expanded — no checkbox,
no chevron, children always visible. This applies to both top-level
labels (Elasticsearch fundamentals, The Elasticsearch Platform, etc.)
and nested labels (Ingest and manage data, Search/visualize, AI/ML).

_TocTreeNavV2.cshtml: for LabelNavigationNode, removed the peer div /
checkbox / chevron pattern; render a plain <span> heading followed by
an always-visible <ul> of children. Removed data-v2-accordion from
label <li> elements since labels no longer participate in accordion.

TOC folder nodes (INodeNavigationItem) retain their existing
checkbox-driven expand/collapse toggle unchanged.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Update nav-v2-status.md: verified behaviours, open items, build commands
3213a5c 
- Verified behaviours: labels always expanded (no toggle), nested
  labels same, placeholders render as disabled, TOC folders still
  toggle, accordion scoped to TOC siblings
- Mark nested label support as done
- Correct build/serve commands to dotnet run invocations
- Note LabelNavigationNode.ExpandedByDefault is now unused

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Style level-2 labels as small-caps dividers to distinguish from level-1
33502f5 
Level-1 labels (top-level sections): font-semibold text-sm text-ink — bold,
14px, full ink colour.

Level-2+ labels (sub-section dividers): text-[10px] font-semibold uppercase
tracking-widest text-ink/50 — all-caps, 10px, wide letter-spacing, 50%
opacity. This is the standard sidebar sub-group treatment (VS Code, Linear,
Notion style) and makes the hierarchy immediately legible at a glance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Level-1 labels: small-caps uppercase + ruled separator between groups
cd3075b 
- Level-1 label text: text-xs uppercase tracking-widest font-semibold
  text-ink — same small-caps treatment as level-2 but full ink colour,
  making them clearly structural dividers not clickable links
- Level-1 label <li>: border-t border-grey-20 pt-4 mt-4 to draw a thin
  horizontal rule between each top-level section; first: variant removes
  the border/padding from the first item

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Improve level-2 label legibility: text-xs at 65% opacity
e0cc136 
Was text-[10px] text-ink/50 — too small and too dim to read comfortably.
Now text-xs (12px) text-ink/65 — same small-caps uppercase treatment,
clearly subordinate to level-1 but readable at a glance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Update nav-v2-status.md: document label typography hierarchy
a870f12 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Add PR link and commit workflow to nav-v2-status.md
41c1ca2 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Add group: placeholder folder type; build Ingest or migrate section
858593e 
Introduces `GroupNavV2Item` — a YAML `group:` item that renders as an
expandable folder with a disabled (cursor-not-allowed) link and a chevron
toggle. Unlike `label:` (always-expanded section heading), `group:` behaves
like a regular TOC folder but with no real URL.

Changes:
- `NavigationV2File.cs`: add `GroupNavV2Item` record + `group:` YAML parsing
- `PlaceholderNavigationNode.cs`: new nav node implementing INodeNavigationItem
- `SiteNavigationV2.cs`: `CreateGroup` builder (mirrors `CreateLabel`)
- `_TocTreeNavV2.cshtml`: render PlaceholderNavigationNode as disabled folder
- `navigation-v2.yml`: replace `toc: manage-data` in "Ingest and manage data"
  with the full "Ingest or migrate: bring your data into Elasticsearch" tree
  (placeholder titles only; no toc/page refs yet)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Fix YAML quoting for group title containing colon
027fcd7 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Build full nav skeleton from JSON IA design
4490cf9 
Translates the complete card-sort JSON into navigation-v2.yml using
group:/title: placeholders throughout. All 6 top-level labels are
populated with the full proposed IA structure — no toc/page refs yet.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Fix CI failures: AOT-compatible deserializer and unused import
c808a6e 
- Switch NavV2Deserializer from DeserializerBuilder to
  StaticDeserializerBuilder — our NavV2FileYamlConverter parses
  manually via parser events so the static context is sufficient;
  fixes IL3050/IL2055 AOT errors in the native build
- Remove unused `$` import from pages-nav-v2.ts; fixes ESLint
  @typescript-eslint/no-unused-vars error in the npm check

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Address code review: LINQ refactor and flatten nested if
1e81481 
- SiteNavigationV2: replace foreach loop in BuildV2Items with
  Select/Where/Cast/ToList chain
- AssemblerBuildService: combine nested ifs into single && condition

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Fix Prettier formatting in pages-nav-v2.ts
99670dd 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Wire up page: cross-link resolution in V2 nav
5c7380b 
Add PageCrossLinkLeaf — resolves a page: URI to a canonical URL using
sitePrefix + URI host + path (minus .md extension). Renders as a real
clickable link via the existing ILeafNavigationItem branch in the Razor
partial, distinct from PlaceholderNavigationLeaf (disabled).

Also wires page: candidates into the "Ingest or migrate" section of
navigation-v2.yml, replacing title: placeholders where content exists.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Fix IDE0370: remove unnecessary null-forgiving operators in SiteNavig…
b7172c6 
…ationV2

The pattern `{ Page: var page }` combined with the prior `{ Page: null }` arm
already guarantees `page` is non-null when this arm matches.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Expand nav to current page on direct URL load
18540af 
Walk up the DOM from the matched link and check each ancestor
collapsible checkbox so the sidebar reveals the active page location
when navigating directly to a URL.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Revert URI-derived path prefix experiment; document limitation in PR
c9160ce 
The file-writing pipeline (GlobalNavigationPathProvider) uses
NavigationTocMappings populated from navigation.yml before
SiteNavigationV2 is constructed, so path prefix overrides in the
navigation model don't reach the output files. Reverted to reusing
V1 nodes directly. Added a URL scheme section to the PR description
explaining the architectural boundary and the intended final design.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Wire Reference section in navigation-v2.yml with real toc and page en…
e7c8292 
…tries

Replace all placeholder title:/group: items in the Reference label with
toc: roots derived from navigation.yml. Remove the redundant
group: Elastic Cloud on Kubernetes (covered by Cloud group) and drop
the [XREF] ECCTL cross-reference. Numeral formatting wired as a
page: cross-link since it lives under explore-analyze, not reference.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
Wire Troubleshooting section with page: cross-links
3fa5e19 
Replace placeholder title: items with real page: entries pointing to
individual troubleshoot pages in docs-content. Keep the five-group
structure (Elasticsearch, Kibana, Observability, Security, Ingestion
tools) rather than collapsing to a single toc: root.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
feat(nav-v2): page-folder group node; migrate section and Reference/T…
69d6c32 
…roubleshooting nav updates

- Add PageFolderNavigationNode: a group node with a real clickable URL,
  used when a group: entry in navigation-v2.yml carries a page: key
- Extend GroupNavV2Item with optional Uri? Page and wire YAML parser
- Update SiteNavigationV2.CreateGroup to emit PageFolderNavigationNode
  when a page is present, PlaceholderNavigationNode otherwise
- Expand "Migrating your Elasticsearch data" placeholder into a real
  page-folder group (migrate.md as parent, four child pages beneath)
- Comment out Reference and Troubleshooting labels in navigation-v2.yml

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
fix(nav-v2): check group: before page: in YAML parser to support page…
9942d3a 
…-folder groups

When a group: item also has a page: key, the old order caused the page:
branch to fire first, returning a raw PageNavV2Item leaf instead of a
GroupNavV2Item. Swap check order so group: always wins when present.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
docs: update nav-v2-status.md to reflect current prototype state
0b4bb8d 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
feat(nav-v2): generate stub pages for placeholder nav items
15b3bef 
Each PlaceholderNavigationLeaf and PlaceholderNavigationNode now gets a
computed URL (/{sitePrefix}/_placeholder/{hash}) and a corresponding
generated stub page (H1 title + "coming soon" paragraph) with the full
site chrome including the V2 nav sidebar.

PlaceholderPageWriter walks the V2 nav tree after the main build and
writes one HTML file per unique placeholder URL to the output directory.
The nav sidebar now renders placeholder links as clickable greyed hrefs
instead of aria-disabled spans — cursor-not-allowed is removed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
docs(nav-v2): update status — placeholder items now generate stub pages
eea7a08 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@theletterf @claude
fix(nav-v2): use absolute URL path prefix for placeholder page static…
db10774 
… assets

env.PathPrefix is "docs" (no leading slash); UrlPathPrefix must be "/docs"
so Static() generates absolute paths like /docs/_static/styles.css instead
of relative paths that resolve incorrectly from /_placeholder/HASH/ depth.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@florent-leborgne @claude
feat(nav-v2): wire Explore/Visualize, Share/Alert/Automate, and AI/ML…
6b953fd 
… sections (#2957)

Replace placeholder title: entries with full-depth page: references for
three navigation sections:

- **Explore and visualize**: Discover, Dashboards, Panels & visualizations
  (Lens, Maps, Canvas, Graph, Legacy editors), Find and organize content.
  Reordered to: Learn → Discover → Dashboards → Panels → Find & organize.

- **Share, alert, and automate** (renamed from "Alert and trigger actions"):
  Reporting and sharing (moved from Explore), Workflows (full depth incl.
  triggers, steps, data handling), Alerting (alerts + full Watcher tree),
  Cases.

- **AI and machine learning**: ML/NLP (anomaly detection, data frame
  analytics, NLP, ML in Kibana), AI framework (Elastic Inference, Agent
  Builder with full tool/agent/programmatic-access tree, AI chats, LLM
  guides), AI agent skills.

All 313 page: entries include title: overrides derived from each file's
navigation_title frontmatter field or cleaned H1 heading.

Both "Explore and visualize" and "Share, alert, and automate" groups now
link to new overview landing pages added in docs-content (hidden pages,
merged via elastic/docs-content#5601).

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne @claude
feat(nav-v2): wire Solutions and project types section with full depth (
8c2d0d8 
#2958)

Replace placeholder title: entries with full-depth page: references for
the Solutions and project types section:

- Solutions overview linked to existing solutions/index.md
- Elasticsearch solution: full hierarchy (Get started, Playground,
  AI Assistant, Query rules, Search Applications, Add-ons)
- Observability solution: full hierarchy (Get started, Applications/APM,
  Synthetics, Logs, Infrastructure, Streams, Incident management, Cloud,
  AI for Observability)
- Security solution: full hierarchy (Get started, AI for Security,
  Detections and alerts, Configure/Manage Elastic Defend, Cloud Security,
  Investigation tools, Dashboards, Entity analytics)
- Search use case excluded per the new IA design

All page: entries include title: overrides from navigation_title or H1.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@itsalexcm @cursoragent
fix(ci): satisfy IDE0028 and Prettier on findability branch
0413c5b 
Use collection-expression with() for Nav V2 lookup dictionaries and format
pages-nav-v2, styles.css, and DeploymentInfo for npm fmt:check.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm @cursoragent
fix(ci): restore hasSameTopLevelGroup and type section shell element
a3f907d 
Fix CS0103 in _TocTreeNav leaf links and TS2339 on dataset by narrowing
closest('.pages-nav-v2-shell') to HTMLElement.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm @cursoragent
fix(ci): set required DeprecationDate and Maturity on unparsable dete…
acdfe4b 
…ction rules

ForUnparsableSource placeholder must initialize fields added in #3167.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 15:26 — with GitHub Actions Inactive
@itsalexcm @cursoragent
fix(ci): restore hub link sandbox skip and hub-pages test snapshots
dcd0992 
Reapply DevelopmentDocs exemption in HubLinkValidator so docs-builder
handbook hub fixtures do not fail assembler preview, and align F# applies-to
snapshots with hub-pages metadata box rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 15:34 — with GitHub Actions Inactive
@itsalexcm @cursoragent
fix(ci): align applies-to F# snapshots with demo/findability
af28be7 
Use test expectations that match main applies-to copy after merging
hub-pages metadata rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 15:40 — with GitHub Actions Inactive
@itsalexcm @cursoragent
fix(synthetics): support landing-page layout in navigation journey
43d143e 
When /docs uses layout: landing-page, navigate via the hero Get started
CTA instead of the sidebar Elastic Fundamentals link.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 16:00 — with GitHub Actions Inactive
@itsalexcm @cursoragent
fix(synthetics): avoid Nav V2 sidebar blocking pages dropdown
7d00a86 
Force-click Reference in the pages dropdown when visible, with a direct
navigation fallback when the sidebar intercepts pointer events.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 16:10 — with GitHub Actions Inactive
@itsalexcm @cursoragent
fix(synthetics): click Reference link via DOM to avoid sidebar overlap
778a5f8 
Programmatic click on the pages-dropdown anchor prevents Nav V2 sidebar
links from receiving mis-targeted force clicks.

Co-authored-by: Cursor <cursoragent@cursor.com>
@itsalexcm itsalexcm temporarily deployed to integration-tests June 23, 2026 16:21 — with GitHub Actions Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@itsalexcm itsalexcm

Labels

redesign enable redesign feature flag

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

10 participants

@itsalexcm @theletterf @florent-leborgne @reakaleek @lcawl @Mpdreamz @cotti @alexandra5000 @shainaraskas @KOTungseth