[ON week experiment] Add tooltips to the nav #2222

leemthompo · 2025-11-17T11:15:04Z

vibe-coded pre-ON week testeroo
probably totally unviable
there were some refactoring in docs-builder in meantime and I merged main fixing conflicts as much as possibl
just pushing to see what CI says at this point 😄

📹

🤖 Summary

Navigation Tooltips Feature Changes

Implementation Summary

Added NavigationTooltip property across the navigation system to display hover tooltips for navigation items:

Interface Change: Added NavigationTooltip property to IDocumentationFile interface
Implementation Pattern:
- Leaf nodes: Delegate to their Model.NavigationTooltip
- Node items: Delegate to their Index.NavigationTooltip
- Root/container items: Return null

Files Modified

Core Implementation:

src/Elastic.Markdown/IO/MarkdownFile.cs - Tooltip logic using description from YAML frontmatter, strips markdown and escapes quotes
src/Elastic.Documentation.Navigation/IDocumentationFile.cs - Added NavigationTooltip property to interface

Navigation Classes (9 files):

src/Elastic.Documentation.Navigation/Assembler/SiteNavigation.cs
src/Elastic.Documentation.Navigation/Isolated/Leaf/CrossLinkNavigationLeaf.cs
src/Elastic.Documentation.Navigation/Isolated/Leaf/FileNavigationLeaf.cs
src/Elastic.Documentation.Navigation/Isolated/Node/DocumentationSetNavigation.cs
src/Elastic.Documentation.Navigation/Isolated/Node/FolderNavigation.cs
src/Elastic.Documentation.Navigation/Isolated/Node/TableOfContentsNavigation.cs
src/Elastic.Documentation.Navigation/Isolated/Node/VirtualFileNavigation.cs
src/Elastic.ApiExplorer/ApiIndexLeafNavigation.cs

Frontend:

src/Elastic.Documentation.Site/Assets/navigation-tooltip.ts - JavaScript implementation
src/Elastic.Documentation.Site/Assets/navigation-tooltip.css - Tooltip styling

Tests:

tests/Elastic.Markdown.Tests/Inline/ImagePathResolutionTests.cs
tests/Navigation.Tests/TestDocumentationSetContext.cs

Integration

Successfully integrated with the refactored navigation system from main branch after merge conflict resolution.

Add a new NavigationTooltip property to the navigation interface and implement it across all navigation item types. The tooltip automatically falls back to the description field if no explicit tooltip is provided. Key changes: - Add navigation_tooltip field to YAML frontmatter parser - Add NavigationTooltip property to INavigationItem interface - Implement NavigationTooltip in MarkdownFile with fallback logic - Replace double quotes with single quotes to prevent HTML attribute issues - Strip markdown formatting from tooltip text - Implement property in all navigation item classes (DocumentationGroup, FileNavigationItem, CrossLinkNavigationItem, OperationNavigationItem, LandingNavigationItem, ApiGroupingNavigationItem, EndpointNavigationItem) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Implement dynamic viewport-relative tooltip positioning using Tippy.js. Tooltips appear after a 500ms hover delay and are styled to match the site's design system with theme support. Key features: - Export initNavigationTooltips() for HTMX re-initialization support - Cleanup logic to destroy previous tooltip instances - Dynamic positioning to prevent viewport overflow - Accessibility: aria-label support and keyboard navigation - Theme-aware styling (light/dark mode) - Arrow indicator pointing to hovered element 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Resolved merge conflicts: - MarkdownFile.cs: Kept navigation tooltip fields from feature branch - Removed old Navigation classes that were refactored in main

Implements NavigationTooltip property across all navigation classes to integrate the tooltip feature with the refactored navigation system from main. Node navigation items delegate tooltips to their Index property, while leaf items get tooltips from their underlying Model.

github-actions · 2025-11-17T11:18:08Z

🔍 Preview links for changed docs

docs/syntax/frontmatter.md

src/Elastic.Markdown/IO/MarkdownFile.cs

…tions are null

src/Elastic.Markdown/IO/MarkdownFile.cs

+		if (!string.IsNullOrEmpty(NavigationTooltip))
+		{
+			if (NavigationTooltip.AsSpan().ReplaceSubstitutions(subs, Collector, out var replacement))
+				NavigationTooltip = replacement;
+		}


leemthompo · 2025-11-20T13:22:03Z

@elastic/docs-engineering if you have any time to gander at this, lemme know if this is anywhere near viable 😄

totally understand if it's not worth the effort to refactor or whatever

colleenmcginnis · 2025-11-20T16:37:00Z

I'd also be curious what @itsalexcm thinks of this from a UX perspective. 🙂

Mpdreamz · 2025-11-20T17:17:49Z

Super neat @leemthompo ! Definitely viable IMO :)

Do we need defaults if its not provided? We might want to back this with querying AI descriptions from our search service if not provided ?

leemthompo · 2025-11-20T17:27:05Z

Do we need defaults if its not provided?

Good question @Mpdreamz, currently it just does nothing if there isn't a description field, but I'm not sure if it's acceptable UX to have some pages not render a tooltip, as we gradually add descriptions.

A related question is that this introduces a new frontmatter field, navigation_tooltip which is theoretically more concise than an SEO description, but seeings as it's hard enough to get descriptions everywhere...that might be a step too far. 😄

We might want to back this with querying AI descriptions from our search service if not provided?

I mean if you could do that, that would be amazing, but sounds complex 🚀

One vague ambition with this was that it would be a tangible incentive to adding descriptions to pages :)

theletterf · 2025-11-26T11:04:05Z

@leemthompo Related? #1838

Mpdreamz · 2025-12-22T09:50:42Z

#1559 would add tooltips for all :)

leemthompo · 2025-12-22T13:40:25Z

Not sure what the next steps are on this TBH, haven't had much time to think about this since ON week. Maybe I'll poll the channel in the new year and see if we want to try to merge this ASAP, or if we want a critical mass of descriptions before doing so 🤔

itsalexcm · 2025-12-23T10:45:01Z

Sorry, I missed this PR. My thoughts, following @colleenmcginnis's curiosity:

I think the idea is interesting as an exploration, but I’m not convinced tooltips are the right pattern for primary navigation.

In navigation, users are usually in a goal-oriented mindset. When they hover an item, they’re not trying to “learn” about it, but deciding whether to click or not. In most cases, they’ll just click and expect the destination page to explain the concept.

Tooltips tend to work better for secondary or supporting UI, where the action isn’t obvious or where clicking is risky or irreversible. Navigation doesn’t usually fall into that category.

More info: Tooltip EUI

leemthompo · 2025-12-23T11:38:27Z

Thanks for chiming in @itsalexcm!

In navigation, users are usually in a goal-oriented mindset. When they hover an item, they’re not trying to “learn” about it, but deciding whether to click or not. In most cases, they’ll just click and expect the destination page to explain the concept.

I'll push back here though, because the whole point of the tooltip is to give some quick visibility into what the page actually contains, to motivate the decision about whether to click or not. If users are "deciding whether to click or not" when hovering, then providing information to help that decision might be useful.

Having to click through multiple pages just to find the right content is frustrating, especially if tooltips could help users navigate more efficiently on the first try.navigation_titles aren't always self-explanatory and the cognitive cost of context-switching between pages is real. Maybe tooltips could reduce that friction.

That said, implementation matters: you'd want them to appear on intentional hover (maybe with a slight delay) rather than aggressive instant tooltips that create noise, plus we do need descriptions that are genuinely helpful in this context.

I'm not sure what the "risk" is, feels like a pretty low-stakes enhancement. We could always ship it as an experiment and see if people actually use them. The feedback would have to be pretty qualitative though, because I don't think it would be easy to get clear telemetry data about stuff like hover times and click throughs that wasn't influenced by tons of other factors.

leemthompo and others added 6 commits November 3, 2025 09:29

Merge branch 'main' into leemthompo/navigation-tooltips

aa31c08

Merge branch 'main' into leemthompo/navigation-tooltips

391d3ca

Merge branch 'main' into leemthompo/navigation-tooltips

27e0154

Resolved merge conflicts: - MarkdownFile.cs: Kept navigation tooltip fields from feature branch - Removed old Navigation classes that were refactored in main

leemthompo self-assigned this Nov 17, 2025

github-actions bot deployed to docs-preview November 17, 2025 11:15 View deployment

leemthompo added the enhancement label Nov 17, 2025

github-code-quality bot found potential problems Nov 17, 2025

View reviewed changes

src/Elastic.Markdown/IO/MarkdownFile.cs Fixed Show fixed Hide fixed

Fix null reference exception in GetSubstitutions when global substitu…

6e8b469

…tions are null

github-actions bot deployed to docs-preview November 17, 2025 11:55 View deployment

Fix Prettier formatting for navigation tooltip files

ef6a425

github-code-quality bot found potential problems Nov 17, 2025

View reviewed changes

src/Elastic.Markdown/IO/MarkdownFile.cs

Comment on lines +190 to +194

if (!string.IsNullOrEmpty(NavigationTooltip))

{

if (NavigationTooltip.AsSpan().ReplaceSubstitutions(subs, Collector, out var replacement))

NavigationTooltip = replacement;

}

Fix null reference when YAML frontmatter Lines is null

0a4081e

github-actions bot deployed to docs-preview November 17, 2025 12:07 View deployment

Add null-coalescing to handle null YamlFrontMatter from deserializer

4c6d1e1

github-actions bot deployed to docs-preview November 17, 2025 12:17 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[ON week experiment] Add tooltips to the nav #2222

[ON week experiment] Add tooltips to the nav #2222

Uh oh!

leemthompo commented Nov 17, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

leemthompo commented Nov 20, 2025 •

edited

Loading

Uh oh!

colleenmcginnis commented Nov 20, 2025

Uh oh!

Mpdreamz commented Nov 20, 2025

Uh oh!

leemthompo commented Nov 20, 2025 •

edited

Loading

Uh oh!

theletterf commented Nov 26, 2025

Uh oh!

Mpdreamz commented Dec 22, 2025

Uh oh!

leemthompo commented Dec 22, 2025

Uh oh!

itsalexcm commented Dec 23, 2025

Uh oh!

leemthompo commented Dec 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

[ON week experiment] Add tooltips to the nav #2222

Are you sure you want to change the base?

[ON week experiment] Add tooltips to the nav #2222

Uh oh!

Conversation

leemthompo commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📹

🤖 Summary

Navigation Tooltips Feature Changes

Implementation Summary

Files Modified

Integration

Uh oh!

github-actions bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

Uh oh!

leemthompo commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colleenmcginnis commented Nov 20, 2025

Uh oh!

Mpdreamz commented Nov 20, 2025

Uh oh!

leemthompo commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theletterf commented Nov 26, 2025

Uh oh!

Mpdreamz commented Dec 22, 2025

Uh oh!

leemthompo commented Dec 22, 2025

Uh oh!

itsalexcm commented Dec 23, 2025

Uh oh!

leemthompo commented Dec 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

leemthompo commented Nov 17, 2025 •

edited

Loading

github-actions bot commented Nov 17, 2025 •

edited

Loading

leemthompo commented Nov 20, 2025 •

edited

Loading

leemthompo commented Nov 20, 2025 •

edited

Loading