Skip to content

Demo findability prototypes together#3256

Draft
theletterf wants to merge 274 commits into
mainfrom
demo/findability
Draft

Demo findability prototypes together#3256
theletterf wants to merge 274 commits into
mainfrom
demo/findability

Conversation

@theletterf
Copy link
Copy Markdown
Member

@theletterf theletterf commented May 6, 2026 •
edited
Loading

Why

This PR provides a single demo branch that reconciles the findability work across the navigation, hub-page, and landing-page prototypes. Keeping them together makes it possible to review and test the end-to-end experience before deciding how to split or sequence production rollout.

URL: https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3256

What

Branch contributions

  • nav-v2 contributes the new IA prototype, label-section navigation model, accordion sidebar behaviour, placeholder page generation, Nav V2 frontend shell, independent sidebar islands, dynamic top-bar sections, API/reference section handling, and related HTMX navigation behaviour. PR: Prototype nav-v2: new IA with label sections, accordion sidebar #2927. The nav-v2-sections work (PR Nav sections: independent sidebar islands and dynamic top bar #3133) has been merged into nav-v2 and is included there.
  • hub-pages builds on nav-v2 with product hub page support, hub-specific directives and styling, product hub routing, product metadata presentation, and Elasticsearch/Kibana hub examples. PR: Findability - prototype - Hub pages #3223.
  • landing-page/prototype adds the search-first documentation landing page prototype, with version disambiguation, popular destinations, getting-started routes, solution browsing, and a product index. PR: [Findability] Landing page prototype #3250.
  • demo/findability reconciles those branches into one branch for demo purposes. It does not add a separate product feature beyond combining the stack.

Estimated hub-page build time

Local forced isolated HTML builds with --skip-api --exporters html showed nav-v2-sections processing 230 files in 1.745s, and this demo branch processing 239 files in 1.804s. That is about +59ms for the hub-page layer and related added docs files in this repo.

Based on that run, budget the marginal cost of each additional hub page in the low tens of milliseconds during isolated HTML generation, roughly <=30ms per page on this machine. Production assembler builds will be dominated by repository checkout, static assets, API/reference work, cross-link fetching, and upload/indexing overhead, so a small number of hub pages should not materially change total build time.

Production rollout considerations

  • Merge order matters: land nav-v2 (which now includes nav-v2-sections), then hub-pages, then the landing-page work, or keep the production branch explicitly stacked until all prerequisites are merged.
  • Keep the Nav V2 and hub-page behaviour gated by configuration or feature flags until the demo has passed design, content, accessibility, and navigation regression testing.
  • Before production, scope the landing-page CSS so resets and generic selectors do not affect the shared header, footer, or embedded React search components.
  • Verify all hub-page URLs, generated placeholder pages, product metadata links, and HTMX swaps in assembler previews, not only isolated docs builds.
  • Revisit build monitoring after adding real product hubs at scale. The current estimate is for the small demo set, and larger hub rollouts should be checked against CI timing and assembler preview timing.

Made with Cursor

theletterf and others added 30 commits March 24, 2026 11:16
@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>
@theletterf
Merge remote-tracking branch 'origin/main' into nav-v2
8c1645c
@theletterf
Merge branch 'nav-v2' of github.com:elastic/docs-builder into nav-v2
0278198
@florent-leborgne @claude
feat(nav-v2): restructure AI and machine learning section (#2965)
6d747b1 
Reorganize the AI and machine learning label for clearer hierarchy:

- **Agent builder**: promoted to top-level group (was nested inside
  AI framework)
- **Elastic Inference Service**: promoted to top-level group
- **Machine Learning and NLP**: unchanged (stays first)
- **AI chat and LLM configuration**: new group combining AI chat
  experiences, LLM provider guides, and AI access management —
  the shared plumbing for platform features that leverage LLMs
- **AI agent skills for Elastic**: unchanged (stays last)

The former "AI framework" wrapper is removed. Its landing page
(ai-features.md) is reused as the page for the new "AI chat and
LLM configuration" group.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf @claude
refactor(nav-v2): promote Ingest tools to L1 under Ingest and manage …
b00e1db 
…data

Moves "Ingest tools (from Reference)" up one level so it sits alongside
"Ingest or migrate" and "Data storage and lifecycle" as a direct child
of the "Ingest and manage data" label.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne
Merge branch 'main' into nav-v2
216ec9c
@florent-leborgne @claude
feat(nav-v2): promote Workflows to its own top-level label (#2976)
c34c969 
Move Workflows out of "Share, alert, and automate" into its own
label section, placed between "Share, alert, and automate" and
"AI and machine learning".

This reflects that Workflows is a distinct platform capability —
not just an extension of alerting — with its own triggers, steps,
data handling, and management surface.

The overview page for "Share, alert, and automate" is updated
separately in docs-content to remove the Workflows section and
add cross-references instead (elastic/docs-content#5661).

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne @claude
feat(nav-v2): rename section to "Track and respond"
afd4977 
Update group name and page reference to match the renamed
docs-content file (elastic/docs-content#5663).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@itsalexcm
feat(nav-v2): sidebar tree, styles, and folder UX
defdce1 
Made-with: Cursor
@itsalexcm
feat(nav-search): polish in-sidebar jump-to-page component
3aa6eee 
Made-with: Cursor
@itsalexcm
style(toc): align in-page and API TOC link padding with sidebar
e60bd4b 
Made-with: Cursor
@itsalexcm
Merge branch 'main' into nav-v2
c08b6e3 
Resolve assembler.yml: keep NAV_V2 under preview and add air-gapped env from main.

Made-with: Cursor
@theletterf @claude
style: fix Prettier formatting in pages-nav-v2.ts and styles.css
1f3f702 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf @claude
Wire Elasticsearch fundamentals and Ingest data storage nav sections (#…
313138a 
…2998)

* feat(nav-v2): wire Elasticsearch fundamentals and Ingest data storage sections

Replace placeholder title: entries with real page: cross-links in two
sections of navigation-v2.yml:

- Elasticsearch fundamentals: Get started, Elasticsearch concepts, and
  Use cases — 8 pages wired from docs-content get-started, manage-data,
  solutions/search, and explore-analyze

- Ingest and manage data > Data storage and lifecycle: The Elasticsearch
  data store, Index basics, Mapping, Text analysis, Data lifecycle — 16
  pages wired from docs-content manage-data and elasticsearch reference

- Ingest and manage data > Transform and enrich data: Data pipelines,
  enrichment, mapping — 6 pages wired from docs-content manage-data and
  opentelemetry reference

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(nav-v2): expand data storage, lifecycle, and transform sections to full depth

Expand flat page: leaf entries into group: + page: + children: structures
mirroring the full manage-data/toc.yml depth:

- Data streams: 18 pages (TSDS, downsampling, logs, failure store)
- Mapping: +7 pages (dynamic, explicit, runtime fields)
- Text analysis: +8 pages (concepts, configure)
- Templates: +2 pages
- ILM: +14 pages (rollover, tutorials, migrate)
- Data stream lifecycle: +4 tutorials
- Rollup: +6 pages
- Ingest pipelines: +3 pages (examples, error handling)
- Data enrichment: +4 examples
- Index basics: +1 page (perform operations)
- Data store: +1 page (near real-time search)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf @claude
Wire Ingest logs, APM agents, and clean up nav labels (#3004)
6a667dc 
* feat(nav-v2): wire Ingest logs, APM agents, and clean up labels

- Replace "Logs (Solutions / Obs)" placeholder with full "Ingest logs"
  group: 20 pages from docs-content://solutions/observability/logs/
- Wire APM agents via toc: docs-content://reference/apm-agents
- Add page: to "Ingest tools" and "Ingest data from applications" groups
- Clean up labels: remove "(New)", "(New - Crosslinks)",
  "(Solutions / Obs)", "(from Reference)" suffixes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(nav-v2): reorder EDOT before Fleet, add Agentless integrations

- Move opentelemetry://reference before docs-content://reference/fleet
  in the Ingest tools section
- Add Agentless integrations group (3 pages) before Ingest data from
  applications

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf
Merge branch 'main' into nav-v2
369e518
@theletterf @claude
feat(nav-v2): rename Agentless group, add integrations reference page
beefc87 
- Rename "Agentless integrations" to "Ingest data with agentless
  integrations"
- Add integration-docs://reference/agentless_integrations.md to the
  agentless group

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf @claude
fix(nav-v2): generate stub pages for placeholders nested inside real …
c4cbed6 
…groups

CollectPlaceholders only recursed into PlaceholderNavigationNode and
LabelNavigationNode, missing placeholders nested inside
PageFolderNavigationNode or TOC nodes. Add a catch-all case for
INodeNavigationItem so all nested placeholders get stub pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@itsalexcm
feat(nav-v2): single-line nav labels with ellipsis and truncated-only…
92d4829 
… tippy tooltips

- Mark nav text with docs-sidebar-nav-v2__nav-text; override text-pretty/word-break for nowrap ellipsis
- Folder rows: min-width 0 and overflow on flex links; grid peer min-width 0
- Tippy: cancel onShow when text is not overflowing; anchor ref for folder links (keyboard focus)
@itsalexcm
feat(nav-v2): ancestor folder highlight and expand/collapse behaviour
6cad4aa 
- Walk ancestor li.group-navigation nodes and add nav-v2-active-ancestor when
  the folder row is not .current (same color as current; chevron uses currentColor).
- Folder row: same URL toggles expand/collapse only; navigating to another URL
  keeps the folder open (checkbox checked) so parent clicks do not collapse the subtree.
- Outside-click collapse leaves folders open when the click target lies on an
  ancestor folder row in the same branch (folderStaysOpenForNavClick).
- Remove any leftover nav-v2-active-label-ancestor class on refresh.
@itsalexcm
style(nav-v2): section labels, tree spacing, and active row chrome
f1c3e2a 
- Set top-level tree li padding-bottom to 32px; margins for label--top and
  label--nested; first nested header under an icon title uses margin-top 12px.
- Remove hardcoded Platform subsection li classes; rely on generic markup and CSS.
- Adjust border and nested label colors to match design.
- Nav link default/hover colors (#1d2a3e, #f1f6ff); wrap label text instead of
  single-line ellipsis; clip nav for Tippy; styles for nav-v2-active-ancestor rows.
- Drop nav-v2-truncate Tippy theme rules (tooltips disabled while text wraps).
@theletterf @claude
feat(nav-v2): move perform-index-operations per docs-content#5279
e4171a2 
Align with elastic/docs-content#5279: move perform-index-operations
from under Index basics to a sibling group under The Elasticsearch
data store, and add new index-operations-reference.md as its child.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@theletterf
Merge branch 'main' into nav-v2
65579de
@theletterf @claude
style: fix Prettier formatting in pages-nav-v2.ts and styles.css
29ba44f 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@itsalexcm
fix(nav-v2): ancestor folder ink and deepest current link
d828f09 
- CSS: force default text colour on nav-v2-active-ancestor rows (keep font-weight); hover/grey-40 variants; scope global #pages-nav .current away from V2 sidebar links.

- JS: when several a.sidebar-link.current share the URL, use the deepest in the tree so subtree/ancestor classes attach to the correct rows.

Made-with: Cursor
theletterf and others added 4 commits May 19, 2026 20:01
@theletterf @codex @cursoragent
Keep nav-v2 focused on the active section
b52c145 
Same-section navigation could leave stale folders expanded, which made the sidebar show multiple open branches. Recomputing expansion from the active page path keeps one relevant branch open and preserves accordion behavior when folders are opened manually.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @codex @cursoragent
Auto-scroll nav-v2 to the active branch
646ed79 
Opening a lower section could still leave part of the active branch clipped below the sidebar viewport. Re-scrolling after the nav layout settles keeps the selected branch fully visible and locks in the behavior with a focused regression test.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @codex @cursoragent
Re-scroll nav-v2 after sidebar chrome resizes
829ec0d 
The Jump to page web component can alter the sidebar chrome after the active branch scroll is first calculated. Observing the sidebar chrome and scroll container makes the active branch scroll correction respond to those late layout changes.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @codex @cursoragent
Format nav-v2 scroll observer
b3834e1 
Prettier wrapped the ResizeObserver map type so the npm formatting check passes in CI.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
theletterf and others added 2 commits May 19, 2026 21:05
@theletterf @codex
Merge main into nav-v2
493cc37 
Bring nav-v2 up to date with main so shared unit test fixes are included before continuing prototype work.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
@theletterf
Merge nav-v2 into demo/findability
f5c40a6 
Bring the demo branch up to date with nav-v2 after nav-v2 was refreshed from main, including shared unit test fixes and latest sidebar behavior.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

# Conflicts:
#	config/navigation-v2.yml
#	src/Elastic.Documentation.Navigation/V2/SiteNavigationV2.cs
#	src/Elastic.Documentation.Site/Assets/styles.css
#	src/Elastic.Markdown/_Layout.cshtml
theletterf and others added 4 commits May 19, 2026 21:13
@theletterf @codex @cursoragent
Fix inline code callouts with links
608a295 
Inline callouts can contain Markdown links, but the parser rejected slash characters and skipped those callouts. Allow slashes in inline callout text and render inline callout Markdown without splitting the list item body so the existing formatting expectation passes.

Co-Authored-By: OpenAI GPT-5.4 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf
Merge remote-tracking branch 'origin/main' into nav-v2
f32801f
@theletterf @codex @cursoragent
Support default-expanded Nav V2 groups
e54dac5 
Allow selected Nav V2 folders to stay open by default without losing manual collapse behavior, so high-priority guide sections remain visible while deeper folders stay collapsed.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf
Merge remote-tracking branch 'origin/nav-v2' into demo/findability
22e7ae3
@theletterf @codex @cursoragent
Fix mobile docs layout overflow
8c7cc8b 
Constrain the page grid and mobile nav chrome so wide header content does not force the docs viewport to scroll horizontally.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @codex @cursoragent
Focus selected duplicate Nav V2 entries
b282107 
Store the clicked sidebar occurrence so duplicate page links keep the user's chosen nav context, while direct loads use a stable canonical fallback.

Co-Authored-By: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf
Copy link
Copy Markdown
Member Author

theletterf commented May 20, 2026

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.

@theletterf @codex @cursoragent
Format Nav V2 duplicate focus script
c21fecf 
Co-Authored-By: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf theletterf temporarily deployed to integration-tests May 20, 2026 11:57 — with GitHub Actions Inactive
@theletterf @codex @cursoragent
Honor same-page duplicate folder selection
b5245a2 
Only treat same-page folder-row clicks as expand toggles when that exact row is already focused, so duplicate rows can still update the selected nav location.

Co-Authored-By: OpenAI GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf theletterf temporarily deployed to integration-tests May 20, 2026 12:46 — with GitHub Actions Inactive
@theletterf @codex @cursoragent
Fix Products dropdown layering
1a0a025 
Allow the desktop Products dropdown to escape the secondary nav scroll container while keeping the Elastic nav above sticky docs chrome.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf @codex @cursoragent
Fix secondary nav overflow cascade
a7df126 
Keep the desktop Products dropdown override outside Tailwind layers so it wins over the overflow utility after builds.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@theletterf theletterf temporarily deployed to integration-tests May 20, 2026 13:22 — with GitHub Actions Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@marciw marciw marciw left review comments

@florent-leborgne florent-leborgne florent-leborgne left review comments

@leemthompo leemthompo leemthompo left review comments

@coderabbitai coderabbitai[bot] coderabbitai[bot] requested changes

@reakaleek reakaleek Awaiting requested review from reakaleek reakaleek is a code owner automatically assigned from elastic/docs-engineering

Requested changes must be addressed to merge this pull request.

Assignees

@theletterf theletterf

Labels

redesign enable redesign feature flag

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.