feat(cli-reference): improve intent pills, add shortcut/alias support

src/Elastic.Documentation.Configuration/Toc/CliReference/CliSchema.cs

@@ -22,7 +22,8 @@ public record CliSchema(
 	string[]? Tags = null,
 	bool? RequiresAuth = null,
 	string[]? AuthCommands = null,
-	CliEnvironmentSchema? Environment = null
+	CliEnvironmentSchema? Environment = null,
+	List<CliShortcutSchema>? Shortcuts = null
 )
 {
 	public static CliSchema Load(IFileInfo schemaFile)
@@ -33,6 +34,8 @@ public static CliSchema Load(IFileInfo schemaFile)
 	}
 }
 
+public record CliShortcutSchema(string From, string[] To);
+
 public record CliCommandSchema(
 	string[] Path,
 	string Name,
@@ -55,10 +58,10 @@ public record CliNamespaceSchema(
 	string Segment,
 	string? Summary,
 	string? Notes,
-	List<CliParamSchema> Options,
+	List<CliParamSchema>? Options,
 	CliDefaultSchema? DefaultCommand,
-	List<CliCommandSchema> Commands,
-	List<CliNamespaceSchema> Namespaces
+	List<CliCommandSchema>? Commands,
+	List<CliNamespaceSchema>? Namespaces
 );
 
 public record CliParamSchema(

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

@@ -484,7 +484,14 @@ INavigationHomeAccessor homeAccessor
 				children.Add(childNav);
 		}
 
-		// All root commands + namespaces from the schema always follow
+		// Shortcut alias pages first, then commands and namespaces
+		foreach (var shortcut in schema.Shortcuts ?? [])
+		{
+			var aliasNav = MakeFileLeaf(docSourceDir, virtualRoot, [shortcut.From], isNamespace: true, childIndex++, folderNavigation, homeAccessor, context);
+			if (aliasNav is not null)
+				children.Add(aliasNav);
+		}
+
 		foreach (var cmd in schema.Commands)
 		{
 			var cmdNav = MakeFileLeaf(docSourceDir, virtualRoot, [cmd.Name], isNamespace: false, childIndex++, folderNavigation, homeAccessor, context);
@@ -532,7 +539,7 @@ IDocumentationSetContext context
 			children.Add(nsIndexNav);
 
 		// Namespace commands
-		foreach (var cmd in ns.Commands)
+		foreach (var cmd in ns.Commands ?? [])
 		{
 			var cmdSegments = segments.Append(cmd.Name).ToArray();
 			var cmdNav = MakeFileLeaf(docSourceDir, virtualRoot, cmdSegments, isNamespace: false, childIndex++, nsFolderNav, homeAccessor, context);
@@ -541,7 +548,7 @@ IDocumentationSetContext context
 		}
 
 		// Sub-namespaces
-		foreach (var subNs in ns.Namespaces)
+		foreach (var subNs in ns.Namespaces ?? [])
 		{
 			var subSegments = segments.Append(subNs.Segment).ToArray();
 			var subNav = BuildNamespaceNavigation(docSourceDir, virtualRoot, subNs, subSegments, childIndex++, nsFolderNav, homeAccessor, context);

src/Elastic.Documentation.Site/Assets/markdown/cli-modifiers.css

@@ -1,13 +1,23 @@
 @layer components {
 	.cli-modifiers {
-		@apply flex flex-wrap gap-2 pb-4;
+		@apply mt-4 mb-4 flex flex-wrap gap-2;
 
 		.cli-modifier {
-			@apply inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium;
+			@apply relative inline-flex cursor-help items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium;
 
 			svg {
 				@apply size-3.5 shrink-0;
 			}
+
+			/* CSS tooltip via data-tooltip attribute */
+			&[data-tooltip]::after {
+				content: attr(data-tooltip);
+				@apply pointer-events-none absolute bottom-full left-1/2 z-50 mb-2 w-max max-w-64 -translate-x-1/2 rounded px-2 py-1 text-xs text-white opacity-0 transition-opacity;
+				background: #1e293b;
+			}
+			&[data-tooltip]:hover::after {
+				@apply opacity-100;
+			}
 		}
 
 		.cli-modifier--destructive {

src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml

@@ -11,14 +11,16 @@
 	{
 		if (raw.StartsWith("[ns]", StringComparison.Ordinal)) return ("ns", raw[4..]);
 		if (raw.StartsWith("[cmd]", StringComparison.Ordinal)) return ("cmd", raw[5..]);
+		if (raw.StartsWith("[alias]", StringComparison.Ordinal)) return ("alias", raw[7..]);
 		return (null, raw);
 	}
 
 	// Inline styles to avoid Tailwind purge — very muted tints, subtle border for definition
-	const string NsStyle  = "background:#f5f3ff;color:#7c3aed;border:1px solid #ddd6fe;";
-	const string CmdStyle = "background:#fffbeb;color:#b45309;border:1px solid #fde68a;";
+	const string NsStyle    = "background:#f5f3ff;color:#7c3aed;border:1px solid #ddd6fe;";
+	const string CmdStyle   = "background:#fffbeb;color:#b45309;border:1px solid #fde68a;";
+	const string AliasStyle = "background:#f0f9ff;color:#0369a1;border:1px solid #bae6fd;";
 
-	static string BadgeStyle(string? badge) => badge == "ns" ? NsStyle : badge == "cmd" ? CmdStyle : "";
+	static string BadgeStyle(string? badge) => badge switch { "ns" => NsStyle, "cmd" => CmdStyle, "alias" => AliasStyle, _ => "" };
 }
 @if (isTopLevel && !Model.IsGlobalAssemblyBuild && !Model.IsPrimaryNavEnabled && !Model.SubTree.Index.Hidden)
 {
@@ -56,6 +58,7 @@
 				<span>@groupLabel</span>
 				@if (groupBadge == "ns") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@NsStyle">ns</span> }
 				else if (groupBadge == "cmd") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@CmdStyle">cmd</span> }
+				else if (groupBadge == "alias") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@AliasStyle">alias</span> }
 			</a>
 		</li>
 	}
@@ -73,6 +76,7 @@
 					<span>@folderLabel</span>
 					@if (folderBadge == "ns") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@NsStyle">ns</span> }
 					else if (folderBadge == "cmd") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@CmdStyle">cmd</span> }
+					else if (folderBadge == "alias") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@AliasStyle">alias</span> }
 				</a>
 				@if (!allHidden)
 				{
@@ -125,6 +129,7 @@
 				<span>@leafLabel</span>
 				@if (leafBadge == "ns") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@NsStyle">ns</span> }
 				else if (leafBadge == "cmd") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@CmdStyle">cmd</span> }
+				else if (leafBadge == "alias") { <span class="ml-auto inline-flex items-center px-1.5 py-0.5 rounded text-[9px] font-bold shrink-0" style="@AliasStyle">alias</span> }
 			</a>
 		</li>
 	}

src/Elastic.Markdown/Extensions/CliReference/CliAliasFile.cs

@@ -0,0 +1,54 @@
+// 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
+
+using System.IO.Abstractions;
+using Elastic.Documentation.Configuration;
+using Elastic.Documentation.Configuration.Toc.CliReference;
+using Elastic.Markdown.Myst;
+using Markdig.Syntax;
+
+namespace Elastic.Markdown.Extensions.CliReference;
+
+public record CliAliasFile : IO.MarkdownFile
+{
+	private readonly CliShortcutSchema _shortcut;
+	private readonly string _binaryName;
+	private readonly string _canonicalRelativePath;
+
+	public CliAliasFile(
+		IFileInfo sourceFile,
+		IDirectoryInfo rootPath,
+		MarkdownParser parser,
+		BuildContext build,
+		CliShortcutSchema shortcut,
+		string binaryName,
+		string canonicalRelativePath
+	) : base(sourceFile, rootPath, parser, build)
+	{
+		_shortcut = shortcut;
+		_binaryName = binaryName;
+		_canonicalRelativePath = canonicalRelativePath;
+		Title = shortcut.From;
+	}
+
+	public override string NavigationTitle => $"[alias]{_shortcut.From}";
+
+	public override string? RedirectUrl => _canonicalRelativePath;
+
+	protected override Task<MarkdownDocument> GetMinimalParseDocumentAsync(Cancel ctx)
+	{
+		Title = _shortcut.From;
+		var markdown = BuildMarkdown();
+		return Task.FromResult(MarkdownParser.MinimalParseStringAsync(markdown, SourceFile, null));
+	}
+
+	protected override Task<MarkdownDocument> GetParseDocumentAsync(Cancel ctx)
+	{
+		var markdown = BuildMarkdown();
+		return Task.FromResult(MarkdownParser.ParseStringAsync(markdown, SourceFile, null));
+	}
+
+	private string BuildMarkdown() =>
+		CliMarkdownGenerator.AliasPage(_shortcut, _binaryName, _canonicalRelativePath);
+}

src/Elastic.Markdown/Extensions/CliReference/CliCommandFile.cs

@@ -17,6 +17,9 @@ public record CliCommandFile : IO.MarkdownFile
 	private readonly string? _binaryName;
 	private readonly string[] _fullPath;
 	private readonly string[]? _reservedMetaCommands;
+	private readonly IReadOnlyList<(string Segment, List<CliParamSchema>? Options)>? _ancestorNamespaceOptions;
+	private readonly List<CliParamSchema>? _globalOptions;
+	private readonly List<CliShortcutSchema>? _shortcuts;
 
 	public CliCommandFile(
 		IFileInfo sourceFile,
@@ -27,14 +30,20 @@ public CliCommandFile(
 		IFileInfo? supplementalDoc,
 		string[]? fullPath = null,
 		string? binaryName = null,
-		string[]? reservedMetaCommands = null
+		string[]? reservedMetaCommands = null,
+		IReadOnlyList<(string Segment, List<CliParamSchema>? Options)>? ancestorNamespaceOptions = null,
+		List<CliParamSchema>? globalOptions = null,
+		List<CliShortcutSchema>? shortcuts = null
 	) : base(sourceFile, rootPath, parser, build)
 	{
 		_command = command;
 		_supplementalDoc = supplementalDoc;
 		_fullPath = fullPath ?? [command.Name];
 		_binaryName = binaryName;
 		_reservedMetaCommands = reservedMetaCommands;
+		_ancestorNamespaceOptions = ancestorNamespaceOptions;
+		_globalOptions = globalOptions;
+		_shortcuts = shortcuts;
 		Title = command.Name;
 	}
 
@@ -60,6 +69,7 @@ private string BuildMarkdown()
 			: null;
 		var supplemental = CliSupplementalDoc.Parse(rawSupplemental);
 		return CliMarkdownGenerator.CommandPage(_command, supplemental, _fullPath, _binaryName, _reservedMetaCommands,
-			error => Collector.EmitError(_supplementalDoc ?? SourceFile, error));
+			error => Collector.EmitError(_supplementalDoc ?? SourceFile, error),
+			_ancestorNamespaceOptions, _globalOptions, _shortcuts);
 	}
 }