[ON week experiment] Add tooltips to the nav

docs/syntax/frontmatter.md

@@ -9,27 +9,50 @@ In the frontmatter block, you can define the following fields:
 ```yaml
 ---
 navigation_title: This is the navigation title <1>
-description: This is a description of the page <2>
-applies_to: <3>
+navigation_tooltip: This is a tooltip shown on hover <2>
+description: This is a description of the page <3>
+applies_to: <4>
   serverless: all
-products: <4>
+products: <5>
   - id: apm-agent
   - id: edot-sdk
-sub: <5>
-  key: value 
+sub: <6>
+  key: value
 ---
 ```
 
 1. [`navigation_title`](#navigation-title)
-2. [`description`](#description)
-3. [`applies_to`](#applies-to)
-4. [`products`](#products)
-5. [`sub`](#subs)
+2. [`navigation_tooltip`](#navigation-tooltip)
+3. [`description`](#description)
+4. [`applies_to`](#applies-to)
+5. [`products`](#products)
+6. [`sub`](#subs)
 
 ## Navigation Title
 
 See [](./titles.md)
 
+## Navigation Tooltip
+
+Use the `navigation_tooltip` frontmatter to set custom tooltip text that appears when hovering over navigation items.
+
+The tooltip is displayed with a 500ms delay when hovering over navigation links in the sidebar and dropdown menus.
+It's positioned dynamically relative to the viewport to avoid overflow issues.
+
+If you don't set a `navigation_tooltip`, it will automatically fall back to the `description` field.
+This provides helpful context for users browsing the navigation without requiring additional configuration.
+
+The `navigation_tooltip` frontmatter is a string. Keep it concise (recommended 50-100 characters) for best readability.
+
+Example:
+
+```yaml
+---
+navigation_title: Quick Start
+navigation_tooltip: Learn how to set up and configure your first application in 5 minutes
+---
+```
+
 ## Description
 
 Use the `description` frontmatter to set the description meta tag for a page.

src/Elastic.ApiExplorer/ApiIndexLeafNavigation.cs

@@ -19,6 +19,9 @@ public class ApiIndexLeafNavigation<TModel>(
 	/// <inheritdoc />
 	public string NavigationTitle { get; } = navigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => null;
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; } = rootNavigation;
 

src/Elastic.ApiExplorer/Landing/LandingNavigationItem.cs

@@ -38,6 +38,8 @@ public class LandingNavigationItem : IApiGroupingNavigationItem<ApiLanding, INav
 
 	public string NavigationTitle => Index.NavigationTitle;
 
+	public string? NavigationTooltip => null; // API landing items don't have tooltips
+
 	public LandingNavigationItem(string url)
 	{
 		NavigationRoot = this;
@@ -73,6 +75,9 @@ INodeNavigationItem<INavigationModel, INavigationItem> parent
 	/// <inheritdoc />
 	public abstract string NavigationTitle { get; }
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => null; // API grouping items don't have tooltips
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; } = rootNavigation;
 
@@ -134,6 +139,9 @@ public class EndpointNavigationItem(ApiEndpoint endpoint, IRootNavigationItem<IA
 	/// <inheritdoc />
 	public string NavigationTitle { get; } = endpoint.Operations.First().ApiName;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => null; // API endpoint items don't have tooltips
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; } = rootNavigation;
 

src/Elastic.ApiExplorer/Operations/OperationNavigationItem.cs

@@ -65,6 +65,8 @@ IApiGroupingNavigationItem<IApiGroupingModel, INavigationItem> parent
 
 	public string NavigationTitle { get; }
 
+	public string? NavigationTooltip => null; // API operations don't have tooltips
+
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
 
 	public int NavigationIndex { get; set; }

src/Elastic.Documentation.Navigation/Assembler/SiteNavigation.cs

@@ -109,6 +109,9 @@ public SiteNavigation(
 	/// <inheritdoc />
 	public string NavigationTitle { get; }
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => null;
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; }
 

src/Elastic.Documentation.Navigation/IDocumentationFile.cs

@@ -10,4 +10,7 @@ public interface IDocumentationFile : INavigationModel
 {
 	/// Gets the title to display in navigation for this documentation file.
 	string NavigationTitle { get; }
+
+	/// Gets the tooltip text to display on hover for this documentation file in navigation.
+	string? NavigationTooltip { get; }
 }

src/Elastic.Documentation.Navigation/INavigationItem.cs

@@ -20,6 +20,9 @@ public interface INavigationItem
 	/// Gets the title displayed in navigation.
 	string NavigationTitle { get; }
 
+	/// Gets the tooltip text displayed on hover for navigation items.
+	string? NavigationTooltip { get; }
+
 	/// Gets the root navigation item.
 	IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; }
 

src/Elastic.Documentation.Navigation/Isolated/Leaf/CrossLinkNavigationLeaf.cs

@@ -11,7 +11,11 @@ namespace Elastic.Documentation.Navigation.Isolated.Leaf;
 /// </summary>
 /// <param name="CrossLinkUri">The URI pointing to the external resource</param>
 /// <param name="NavigationTitle">The title to display in navigation</param>
-public record CrossLinkModel(Uri CrossLinkUri, string NavigationTitle) : IDocumentationFile;
+public record CrossLinkModel(Uri CrossLinkUri, string NavigationTitle) : IDocumentationFile
+{
+	/// <inheritdoc />
+	public string? NavigationTooltip => null;
+}
 
 [DebuggerDisplay("{Url}")]
 public class CrossLinkNavigationLeaf(
@@ -41,6 +45,9 @@ INavigationHomeAccessor homeAccessor
 	/// <inheritdoc />
 	public string NavigationTitle => Model.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Model.NavigationTooltip;
+
 	/// <inheritdoc />
 	public int NavigationIndex { get; set; }
 

src/Elastic.Documentation.Navigation/Isolated/Leaf/FileNavigationLeaf.cs

@@ -74,6 +74,9 @@ string DetermineUrl()
 	/// <inheritdoc />
 	public string NavigationTitle => Model.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Model.NavigationTooltip;
+
 	/// <inheritdoc />
 	public int NavigationIndex { get; set; }
 

src/Elastic.Documentation.Navigation/Isolated/Node/DocumentationSetNavigation.cs

@@ -117,6 +117,9 @@ public DocumentationSetNavigation(
 	/// <inheritdoc />
 	public string NavigationTitle => Index.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Index.NavigationTooltip;
+
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot =>
 		HomeProvider == this ? field : HomeProvider.NavigationRoot;
 

src/Elastic.Documentation.Navigation/Isolated/Node/FolderNavigation.cs

@@ -25,6 +25,9 @@ public class FolderNavigation<TModel>(
 	/// <inheritdoc />
 	public string NavigationTitle => Index.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Index.NavigationTooltip;
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot => homeAccessor.HomeProvider.NavigationRoot;
 

src/Elastic.Documentation.Navigation/Isolated/Node/TableOfContentsNavigation.cs

@@ -58,6 +58,9 @@ INavigationHomeProvider homeProvider
 	/// <inheritdoc />
 	public string NavigationTitle => Index.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Index.NavigationTooltip;
+
 	/// <summary>
 	/// TableOfContentsNavigation's NavigationRoot comes from its HomeProvider.
 	/// According to url-building.md: "In isolated builds the NavigationRoot is always the DocumentationSetNavigation"

src/Elastic.Documentation.Navigation/Isolated/Node/VirtualFileNavigation.cs

@@ -21,6 +21,9 @@ public class VirtualFileNavigation<TModel>(TModel model, IFileInfo fileInfo, Vir
 	/// <inheritdoc />
 	public string NavigationTitle => Index.NavigationTitle;
 
+	/// <inheritdoc />
+	public string? NavigationTooltip => Index.NavigationTooltip;
+
 	/// <inheritdoc />
 	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot => args.HomeAccessor.HomeProvider.NavigationRoot;
 

src/Elastic.Documentation.Site/Assets/main.ts

@@ -3,6 +3,7 @@ import { initCopyButton } from './copybutton'
 import { initHighlight } from './hljs'
 import { initImageCarousel } from './image-carousel'
 import './markdown/applies-to'
+import { initNavigationTooltips } from './navigation-tooltip'
 import { openDetailsWithAnchor } from './open-details-with-anchor'
 import { initNav } from './pages-nav'
 import { initSmoothScroll } from './smooth-scroll'
@@ -81,6 +82,7 @@ document.addEventListener('htmx:load', function (event: HtmxEvent) {
     initTabs()
     initAppliesSwitch()
     initMath()
+    initNavigationTooltips()
 
     // We do this so that the navigation is not initialized twice
     if (isLazyLoadNavigationEnabled) {

src/Elastic.Documentation.Site/Assets/navigation-tooltip.css

@@ -0,0 +1,75 @@
+/* Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+ * See the LICENSE file in the project root for more information
+ */
+
+/**
+ * Navigation Tooltip Styles
+ * Viewport-positioned tooltips for navigation items
+ */
+
+.nav-tooltip {
+	position: fixed;
+	padding: 8px 12px;
+	background-color: #1a1c21;
+	color: #ffffff;
+	font-size: 13px;
+	line-height: 1.4;
+	border-radius: 4px;
+	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+	max-width: 320px;
+	word-wrap: break-word;
+	white-space: normal;
+	opacity: 0;
+	visibility: hidden;
+	transition:
+		opacity 0.2s ease-in-out,
+		visibility 0.2s ease-in-out;
+	pointer-events: none;
+	z-index: 10000;
+}
+
+.nav-tooltip--visible {
+	opacity: 1;
+	visibility: visible;
+}
+
+/* Arrow indicator pointing to the nav item */
+.nav-tooltip::before {
+	content: '';
+	position: absolute;
+	left: -6px;
+	top: 50%;
+	transform: translateY(-50%);
+	width: 0;
+	height: 0;
+	border-style: solid;
+	border-width: 6px 6px 6px 0;
+	border-color: transparent #1a1c21 transparent transparent;
+}
+
+/* Light theme support */
+@media (prefers-color-scheme: light) {
+	.nav-tooltip {
+		background-color: #343741;
+		color: #ffffff;
+	}
+
+	.nav-tooltip::before {
+		border-color: transparent #343741 transparent transparent;
+	}
+}
+
+/* High contrast mode support */
+@media (prefers-contrast: high) {
+	.nav-tooltip {
+		border: 1px solid currentColor;
+	}
+}
+
+/* Reduced motion support */
+@media (prefers-reduced-motion: reduce) {
+	.nav-tooltip {
+		transition: none;
+	}
+}