Nav sections: independent sidebar islands and dynamic top bar

src/Elastic.Codex/Page/Index.cshtml

@@ -49,6 +49,8 @@
 		Previous = Model.PreviousDocument,
 		Next = Model.NextDocument,
 		NavigationHtml = Model.NavigationHtml,
+		NavV2Sections = Model.NavV2Sections,
+		ActiveSectionId = Model.ActiveSectionId,
 		UrlPathPrefix = Model.UrlPathPrefix,
 		GithubEditUrl = Model.GithubEditUrl,
 		MarkdownUrl = Model.MarkdownUrl,

src/Elastic.Documentation.Configuration/Toc/NavigationV2File.cs

@@ -27,6 +27,28 @@ IReadOnlyList<INavV2Item> Children
 /// </summary>
 public record PageNavV2Item(Uri? Page, string? Title) : INavV2Item;
 
+/// <summary>
+/// A top-level section that owns an independent sidebar tree and (optionally) a tab in the
+/// secondary nav bar. When <see cref="Isolated"/> is <c>true</c> the section does not appear
+/// in the top bar and renders with a back-arrow instead.
+/// </summary>
+public record SectionNavV2Item(
+	string Label,
+	string Url,
+	bool Isolated,
+	IReadOnlyList<INavV2Item> Children
+) : INavV2Item;
+
+/// <summary>
+/// A nav island nested inside a section. When a user navigates into pages belonging to
+/// this island's toc, the sidebar shows only the island's tree with a back arrow to the
+/// parent section. The island does not appear in the secondary nav bar.
+/// </summary>
+public record IslandNavV2Item(
+	string Label,
+	Uri Source
+) : INavV2Item;
+
 /// <summary>
 /// A folder node — has a title and children, with an optional <c>page:</c> URI.
 /// When <see cref="Page"/> is set, the header is a real clickable link; otherwise it renders
@@ -110,6 +132,30 @@ private static IReadOnlyList<INavV2Item> ReadItemList(IParser parser, ObjectDese
 				parser.SkipThisAndNestedEvents();
 		}
 
+		if (dict.TryGetValue("section", out var sectionVal) && sectionVal is string sectionStr)
+		{
+			var sectionUrl = dict.TryGetValue("url", out var suVal) && suVal is string suStr ? suStr : "/";
+			var isolated = dict.TryGetValue("isolated", out var isoVal)
+				&& isoVal is string isoStr
+				&& bool.TryParse(isoStr, out var isoBool)
+				&& isoBool;
+			var sectionChildren = dict.TryGetValue("children", out var sch) && sch is IReadOnlyList<INavV2Item> sChildList
+				? sChildList
+				: [];
+			return new SectionNavV2Item(sectionStr, sectionUrl, isolated, sectionChildren);
+		}
+
+		if (dict.TryGetValue("island", out var islandVal) && islandVal is string islandStr)
+		{
+			if (dict.TryGetValue("toc", out var itVal) && itVal is string itStr)
+			{
+				var itUriString = itStr.Contains("://") ? itStr : $"docs-content://{itStr}";
+				if (Uri.TryCreate(itUriString, UriKind.Absolute, out var itSource))
+					return new IslandNavV2Item(islandStr, itSource);
+			}
+			return null;
+		}
+
 		if (dict.TryGetValue("label", out var labelVal) && labelVal is string labelStr)
 		{
 			var expanded = dict.TryGetValue("expanded", out var expVal)

src/Elastic.Documentation.Navigation/V2/IslandNavigationNode.cs

@@ -0,0 +1,49 @@
+// 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 Elastic.Documentation.Extensions;
+
+namespace Elastic.Documentation.Navigation.V2;
+
+/// <summary>
+/// A nav island that wraps an existing toc node. When a page belongs to this island,
+/// the sidebar shows only the island's tree with a back arrow to the parent section.
+/// In the parent section's sidebar, the island renders as a normal folder link.
+/// </summary>
+public class IslandNavigationNode(
+	string label,
+	IRootNavigationItem<IDocumentationFile, INavigationItem> source,
+	INodeNavigationItem<INavigationModel, INavigationItem>? parent
+) : INodeNavigationItem<INavigationModel, INavigationItem>
+{
+	/// <summary>The Id of the wrapped toc root, used for island lookup by nav ownership.</summary>
+	public string SourceTocRootId { get; } = source.Id;
+
+	/// <inheritdoc />
+	public string Id { get; } = ShortId.Create("island", label);
+
+	/// <inheritdoc />
+	public string Url => source.Url;
+
+	/// <inheritdoc />
+	public string NavigationTitle { get; } = label;
+
+	/// <inheritdoc />
+	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; } = parent?.NavigationRoot!;
+
+	/// <inheritdoc />
+	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; } = parent;
+
+	/// <inheritdoc />
+	public bool Hidden => source.Hidden;
+
+	/// <inheritdoc />
+	public int NavigationIndex { get; set; }
+
+	/// <inheritdoc />
+	public ILeafNavigationItem<INavigationModel> Index => source.Index;
+
+	/// <inheritdoc />
+	public IReadOnlyCollection<INavigationItem> NavigationItems => source.NavigationItems;
+}

src/Elastic.Documentation.Navigation/V2/NavigationSection.cs

@@ -0,0 +1,30 @@
+// 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
+
+namespace Elastic.Documentation.Navigation.V2;
+
+/// <summary>
+/// Lightweight data carrier for a navigation section, used by the rendering layer
+/// to drive the secondary nav bar tabs and resolve which sidebar to show.
+/// </summary>
+public record NavigationSection(
+	string Id,
+	string Label,
+	string Url,
+	bool Isolated,
+	IReadOnlyList<INavigationItem> NavigationItems
+);
+
+/// <summary>
+/// A nav island nested within a parent section. When a page belongs to an island,
+/// the sidebar shows only the island's tree with a back arrow to the parent section.
+/// </summary>
+public record NavigationIsland(
+	string Id,
+	string Label,
+	string Url,
+	string SourceTocRootId,
+	NavigationSection ParentSection,
+	IReadOnlyList<INavigationItem> NavigationItems
+);

src/Elastic.Documentation.Navigation/V2/SectionNavigationNode.cs

@@ -0,0 +1,77 @@
+// 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 Elastic.Documentation.Extensions;
+
+namespace Elastic.Documentation.Navigation.V2;
+
+/// <summary>
+/// A top-level section that owns an independent sidebar nav tree.
+/// Unlike <see cref="LabelNavigationNode"/>, a section has a real URL (the tab link)
+/// and an <see cref="Isolated"/> flag that controls whether it appears in the top bar.
+/// </summary>
+public class SectionNavigationNode : INodeNavigationItem<INavigationModel, INavigationItem>
+{
+	private readonly SectionIndexLeaf _index;
+
+	public SectionNavigationNode(
+		string label,
+		string url,
+		bool isolated,
+		IReadOnlyCollection<INavigationItem> children,
+		INodeNavigationItem<INavigationModel, INavigationItem>? parent
+	)
+	{
+		Id = ShortId.Create("section", label);
+		NavigationTitle = label;
+		Url = url;
+		Isolated = isolated;
+		NavigationItems = children;
+		Parent = parent;
+		NavigationRoot = parent?.NavigationRoot!;
+		_index = new SectionIndexLeaf(this);
+	}
+
+	/// <summary>Whether this section is excluded from the top bar and renders with a back arrow.</summary>
+	public bool Isolated { get; }
+
+	/// <inheritdoc />
+	public string Id { get; }
+
+	/// <inheritdoc />
+	public string Url { get; }
+
+	/// <inheritdoc />
+	public string NavigationTitle { get; }
+
+	/// <inheritdoc />
+	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; }
+
+	/// <inheritdoc />
+	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
+
+	/// <inheritdoc />
+	public bool Hidden => false;
+
+	/// <inheritdoc />
+	public int NavigationIndex { get; set; }
+
+	/// <inheritdoc />
+	public ILeafNavigationItem<INavigationModel> Index => _index;
+
+	/// <inheritdoc />
+	public IReadOnlyCollection<INavigationItem> NavigationItems { get; }
+
+	private sealed class SectionIndexLeaf(SectionNavigationNode owner)
+		: ILeafNavigationItem<INavigationModel>, INavigationModel
+	{
+		public INavigationModel Model => this;
+		public string Url => owner.Url;
+		public string NavigationTitle => owner.NavigationTitle;
+		public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot => owner.NavigationRoot;
+		public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; } = owner;
+		public bool Hidden => true;
+		public int NavigationIndex { get; set; }
+	}
+}