PoC: Lazy loaded navigation (#1505)

reakaleek · web-flow · commit 4e9dcc920e36 · 2025-07-02T18:10:23.000+02:00
* PoC: Lazy loaded navigation

* Hide functionality behind the LAZY_LOAD_NAVIGATION feature flag

* Refactor
diff --git a/src/Elastic.ApiExplorer/OpenApiGenerator.cs b/src/Elastic.ApiExplorer/OpenApiGenerator.cs
@@ -288,7 +288,7 @@ private async Task<IFileInfo> Render<T>(INavigationItem current, T page, ApiRend
 		if (!outputFile.Directory!.Exists)
 			outputFile.Directory.Create();
 
-		var navigationHtml = await navigationRenderer.RenderNavigation(current.NavigationRoot, new Uri("http://ignored.example"), ctx);
+		var navigationHtml = await navigationRenderer.RenderNavigation(current.NavigationRoot, new Uri("http://ignored.example"), INavigationHtmlWriter.AllLevels, ctx);
 		renderContext = renderContext with
 		{
 			CurrentNavigation = current,
diff --git a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs
@@ -20,6 +20,12 @@ public bool PrimaryNavEnabled
 		set => _featureFlags["primary-nav"] = value;
 	}
 
+	public bool LazyLoadNavigation
+	{
+		get => IsEnabled("LAZY_LOAD_NAVIGATION");
+		set => _featureFlags["LAZY_LOAD_NAVIGATION"] = value;
+	}
+
 	private bool IsEnabled(string key)
 	{
 		var envKey = $"FEATURE_{key.ToUpperInvariant().Replace('-', '_')}";
diff --git a/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml b/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
@@ -1,5 +1,10 @@
 @inherits RazorSlice<Elastic.Documentation.Site.GlobalLayoutViewModel>
 <aside class="sidebar bg-white fixed md:sticky shadow-2xl md:shadow-none left-[100%] group-has-[#pages-nav-hamburger:checked]/body:left-0 bottom-0 md:left-auto pl-6 md:pl-2 top-[calc(var(--offset-top)+1px)] w-[80%] md:w-auto shrink-0 border-r-1 border-r-grey-20 z-40 md:z-auto">
+	
+	@if (Model.Features.LazyLoadNavigation)
+	{
+		<div hx-get="@(Model.CurrentNavigationItem.Url + (Model.CurrentNavigationItem.Url.EndsWith('/') ? "index.nav.html" : "/index.nav.html"))" hx-trigger="load" hx-params="nav" hx-push-url="false" hx-swap="innerHTML" hx-target="#pages-nav"></div>
+	}
 	<nav
 		id="pages-nav"
 		class="sidebar-nav h-full">
diff --git a/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs b/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
@@ -8,7 +8,9 @@ namespace Elastic.Documentation.Site.Navigation;
 
 public interface INavigationHtmlWriter
 {
-	Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, Cancel ctx = default);
+	const int AllLevels = -1;
+
+	Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, int maxLevel, Cancel ctx = default);
 
 	async Task<string> Render(NavigationViewModel model, Cancel ctx)
 	{
diff --git a/src/Elastic.Documentation.Site/Navigation/IsolatedBuildNavigationHtmlWriter.cs b/src/Elastic.Documentation.Site/Navigation/IsolatedBuildNavigationHtmlWriter.cs
@@ -10,24 +10,24 @@ namespace Elastic.Documentation.Site.Navigation;
 public class IsolatedBuildNavigationHtmlWriter(BuildContext context, IRootNavigationItem<INavigationModel, INavigationItem> siteRoot)
 	: INavigationHtmlWriter
 {
-	private readonly ConcurrentDictionary<string, string> _renderedNavigationCache = [];
+	private readonly ConcurrentDictionary<(string, int), string> _renderedNavigationCache = [];
 
-	public async Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, Cancel ctx = default)
+	public async Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, int maxLevel, Cancel ctx = default)
 	{
 		var navigation = context.Configuration.Features.PrimaryNavEnabled || currentRootNavigation.IsUsingNavigationDropdown
 			? currentRootNavigation
 			: siteRoot;
 
-		if (_renderedNavigationCache.TryGetValue(navigation.Id, out var value))
+		if (_renderedNavigationCache.TryGetValue((navigation.Id, maxLevel), out var value))
 			return value;
 
-		var model = CreateNavigationModel(navigation);
+		var model = CreateNavigationModel(navigation, maxLevel);
 		value = await ((INavigationHtmlWriter)this).Render(model, ctx);
-		_renderedNavigationCache[navigation.Id] = value;
+		_renderedNavigationCache[(navigation.Id, maxLevel)] = value;
 		return value;
 	}
 
-	private NavigationViewModel CreateNavigationModel(IRootNavigationItem<INavigationModel, INavigationItem> navigation) =>
+	private NavigationViewModel CreateNavigationModel(IRootNavigationItem<INavigationModel, INavigationItem> navigation, int maxLevel) =>
 		new()
 		{
 			Title = navigation.NavigationTitle,
@@ -36,6 +36,7 @@ private NavigationViewModel CreateNavigationModel(IRootNavigationItem<INavigatio
 			IsPrimaryNavEnabled = context.Configuration.Features.PrimaryNavEnabled,
 			IsUsingNavigationDropdown = context.Configuration.Features.PrimaryNavEnabled || navigation.IsUsingNavigationDropdown,
 			IsGlobalAssemblyBuild = false,
-			TopLevelItems = siteRoot.NavigationItems.OfType<INodeNavigationItem<INavigationModel, INavigationItem>>().ToList()
+			TopLevelItems = siteRoot.NavigationItems.OfType<INodeNavigationItem<INavigationModel, INavigationItem>>().ToList(),
+			MaxLevel = maxLevel
 		};
 }
diff --git a/src/Elastic.Documentation.Site/Navigation/NavigationTreeItem.cs b/src/Elastic.Documentation.Site/Navigation/NavigationTreeItem.cs
@@ -12,4 +12,6 @@ public class NavigationTreeItem
 	public required bool IsPrimaryNavEnabled { get; init; }
 	public required bool IsGlobalAssemblyBuild { get; init; }
 	public required string RootNavigationId { get; set; }
+	// How many levels to render. Default is -1 (all levels)
+	public required int MaxLevel { get; init; }
 }
diff --git a/src/Elastic.Documentation.Site/Navigation/NavigationViewModel.cs b/src/Elastic.Documentation.Site/Navigation/NavigationViewModel.cs
@@ -15,4 +15,7 @@ public class NavigationViewModel
 
 	/// controls whether to split the navigation tree automatically
 	public required bool IsUsingNavigationDropdown { get; init; }
+
+	// How many levels to render. -1 means all
+	public required int MaxLevel { get; init; }
 }
diff --git a/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml b/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml
@@ -1,5 +1,6 @@
 @using Elastic.Documentation.Site.Navigation
 @inherits RazorSlice<Elastic.Documentation.Site.Navigation.NavigationViewModel>
+
 <div class="pb-20 font-body">
 	@{
 		var currentTopLevelItem = Model.TopLevelItems.FirstOrDefault(i => i.Id == Model.Tree.Id) ?? Model.Tree;
@@ -65,6 +66,7 @@
 			Level = 0,
 			SubTree = Model.Tree,
 			RootNavigationId = Model.Tree.Id,
+			MaxLevel = Model.MaxLevel
 		}))
 	</ul>
 </div>
diff --git a/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml b/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml
@@ -57,15 +57,22 @@
 			</div>
 			@if (g.NavigationItems.Count > 0)
 			{
+				// Only render children if we're within the allowed level depth
+				// MaxLevel of -1 means render all levels
+				bool shouldRenderChildren = Model.MaxLevel == -1 || Model.Level < (Model.MaxLevel);
 				<ul class="w-full hidden peer-has-checked:block ml-4">
-					@await RenderPartialAsync(_TocTreeNav.Create(new NavigationTreeItem
+					@if (shouldRenderChildren)
 					{
-						IsPrimaryNavEnabled = Model.IsPrimaryNavEnabled,
-						IsGlobalAssemblyBuild = Model.IsGlobalAssemblyBuild,
-						Level = Model.Level + 1,
-						SubTree = g,
-						RootNavigationId = Model.RootNavigationId
-					}))
+						@await RenderPartialAsync(_TocTreeNav.Create(new NavigationTreeItem
+						{
+							IsPrimaryNavEnabled = Model.IsPrimaryNavEnabled,
+							IsGlobalAssemblyBuild = Model.IsGlobalAssemblyBuild,
+							Level = Model.Level + 1,
+							SubTree = g,
+							RootNavigationId = Model.RootNavigationId,
+							MaxLevel = Model.MaxLevel
+						}))
+					}
 				</ul>
 			}
 		</li>
diff --git a/src/Elastic.Markdown/DocumentationGenerator.cs b/src/Elastic.Markdown/DocumentationGenerator.cs
@@ -334,7 +334,7 @@ private async Task GenerateDocumentationState(Cancel ctx)
 		await DocumentationSet.OutputDirectory.FileSystem.File.WriteAllBytesAsync(stateFile.FullName, bytes, ctx);
 	}
 
-	public async Task<string?> RenderLayout(MarkdownFile markdown, Cancel ctx)
+	public async Task<RenderResult> RenderLayout(MarkdownFile markdown, Cancel ctx)
 	{
 		await DocumentationSet.Tree.Resolve(ctx);
 		return await HtmlWriter.RenderLayout(markdown, ctx);
diff --git a/src/Elastic.Markdown/HtmlWriter.cs b/src/Elastic.Markdown/HtmlWriter.cs
@@ -44,18 +44,21 @@ public string Render(string markdown, IFileInfo? source)
 		return MarkdownFile.CreateHtml(parsed);
 	}
 
-	public async Task<string> RenderLayout(MarkdownFile markdown, Cancel ctx = default)
+	public async Task<RenderResult> RenderLayout(MarkdownFile markdown, Cancel ctx = default)
 	{
 		var document = await markdown.ParseFullAsync(ctx);
 		return await RenderLayout(markdown, document, ctx);
 	}
 
-	private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument document, Cancel ctx = default)
+	private async Task<RenderResult> RenderLayout(MarkdownFile markdown, MarkdownDocument document, Cancel ctx = default)
 	{
 		var html = MarkdownFile.CreateHtml(document);
 		await DocumentationSet.Tree.Resolve(ctx);
 
-		var navigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, ctx);
+		var fullNavigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, INavigationHtmlWriter.AllLevels, ctx);
+		var miniNavigationHtml = DocumentationSet.Context.Configuration.Features.LazyLoadNavigation
+			? await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, 1, ctx)
+			: "lazy navigation feature disabled";
 
 		var current = PositionalNavigation.GetCurrent(markdown);
 		var previous = PositionalNavigation.GetPrevious(markdown);
@@ -115,7 +118,7 @@ private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument
 			PreviousDocument = previous,
 			NextDocument = next,
 			Parents = parents,
-			NavigationHtml = navigationHtml,
+			NavigationHtml = DocumentationSet.Configuration.Features.LazyLoadNavigation ? miniNavigationHtml : fullNavigationHtml,
 			UrlPathPrefix = markdown.UrlPathPrefix,
 			AppliesTo = markdown.YamlFrontMatter?.AppliesTo,
 			GithubEditUrl = editUrl,
@@ -132,7 +135,12 @@ private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument
 			Products = allProducts,
 			VersionsConfig = DocumentationSet.Context.VersionsConfig
 		});
-		return await slice.RenderAsync(cancellationToken: ctx);
+		return new RenderResult
+		{
+			Html = await slice.RenderAsync(cancellationToken: ctx),
+			FullNavigationPartialHtml = fullNavigationHtml
+		};
+
 	}
 
 	public async Task<MarkdownDocument> WriteAsync(IFileInfo outputFile, MarkdownFile markdown, IConversionCollector? collector, Cancel ctx = default)
@@ -160,9 +168,20 @@ public async Task<MarkdownDocument> WriteAsync(IFileInfo outputFile, MarkdownFil
 		var document = await markdown.ParseFullAsync(ctx);
 
 		var rendered = await RenderLayout(markdown, document, ctx);
-		collector?.Collect(markdown, document, rendered);
-		await writeFileSystem.File.WriteAllTextAsync(path, rendered, ctx);
+		collector?.Collect(markdown, document, rendered.Html);
+		await writeFileSystem.File.WriteAllTextAsync(path, rendered.Html, ctx);
+
+		if (DocumentationSet.Configuration.Features.LazyLoadNavigation)
+		{
+			await writeFileSystem.File.WriteAllTextAsync(path.Replace(".html", ".nav.html"), rendered.FullNavigationPartialHtml, ctx);
+		}
 		return document;
 	}
 
 }
+
+public record RenderResult
+{
+	public required string Html { get; init; }
+	public required string FullNavigationPartialHtml { get; init; }
+}
diff --git a/src/tooling/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs b/src/tooling/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs
@@ -17,7 +17,7 @@ public class GlobalNavigationHtmlWriter(
 	AssembleSources assembleSources
 ) : INavigationHtmlWriter
 {
-	private readonly ConcurrentDictionary<Uri, string> _renderedNavigationCache = [];
+	private readonly ConcurrentDictionary<(Uri, int), string> _renderedNavigationCache = [];
 
 	private ImmutableHashSet<Uri> Phantoms { get; } = [.. navigationFile.Phantoms.Select(p => p.Source)];
 
@@ -44,7 +44,7 @@ private bool TryGetNavigationRoot(
 		return true;
 	}
 
-	public async Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, Cancel ctx = default)
+	public async Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, int maxLevel = -1, Cancel ctx = default)
 	{
 		if (Phantoms.Contains(navigationSource))
 			return string.Empty;
@@ -55,25 +55,25 @@ public async Task<string> RenderNavigation(IRootNavigationItem<INavigationModel,
 		if (Phantoms.Contains(navigationRootSource))
 			return string.Empty;
 
-		if (_renderedNavigationCache.TryGetValue(navigationRootSource, out var value))
+		if (_renderedNavigationCache.TryGetValue((navigationRootSource, maxLevel), out var value))
 			return value;
 
 		if (navigationRootSource == new Uri("docs-content:///"))
 		{
-			_renderedNavigationCache[navigationRootSource] = string.Empty;
+			_renderedNavigationCache[(navigationRootSource, maxLevel)] = string.Empty;
 			return string.Empty;
 		}
 
 		Console.WriteLine($"Rendering navigation for {navigationRootSource}");
 
-		var model = CreateNavigationModel(navigationRoot);
+		var model = CreateNavigationModel(navigationRoot, maxLevel);
 		value = await ((INavigationHtmlWriter)this).Render(model, ctx);
-		_renderedNavigationCache[navigationRootSource] = value;
+		_renderedNavigationCache[(navigationRootSource, maxLevel)] = value;
 
 		return value;
 	}
 
-	private NavigationViewModel CreateNavigationModel(DocumentationGroup group)
+	private NavigationViewModel CreateNavigationModel(DocumentationGroup group, int maxLevel)
 	{
 		var topLevelItems = globalNavigation.TopLevelItems;
 		return new NavigationViewModel
@@ -84,7 +84,8 @@ private NavigationViewModel CreateNavigationModel(DocumentationGroup group)
 			IsPrimaryNavEnabled = true,
 			IsUsingNavigationDropdown = true,
 			IsGlobalAssemblyBuild = true,
-			TopLevelItems = topLevelItems
+			TopLevelItems = topLevelItems,
+			MaxLevel = maxLevel
 		};
 	}
 }
diff --git a/src/tooling/docs-assembler/assembler.yml b/src/tooling/docs-assembler/assembler.yml
@@ -23,6 +23,8 @@ environments:
     content_source: current
     google_tag_manager:
       enabled: false
+    feature_flags:
+      LAZY_LOAD_NAVIGATION: true
   dev:
     uri: http://localhost:4000
     content_source: next
diff --git a/src/tooling/docs-builder/Http/DocumentationWebHost.cs b/src/tooling/docs-builder/Http/DocumentationWebHost.cs
@@ -180,11 +180,16 @@ private async Task<IResult> ServeApiFile(ReloadableGeneratorState holder, string
 	private static async Task<IResult> ServeDocumentationFile(ReloadableGeneratorState holder, string slug, Cancel ctx)
 	{
 		var generator = holder.Generator;
-
+		const string navPartialSuffix = "index.nav.html";
+		var isNavPartial = slug.EndsWith(navPartialSuffix);
 		if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
 			slug = slug.Replace('/', Path.DirectorySeparatorChar);
 
+		if (isNavPartial)
+			slug = slug.Replace(navPartialSuffix, "index.md");
+
 		var s = Path.GetExtension(slug) == string.Empty ? Path.Combine(slug, "index.md") : slug;
+
 		if (!generator.DocumentationSet.FlatMappedFiles.TryGetValue(s, out var documentationFile))
 		{
 			s = Path.GetExtension(slug) == string.Empty ? slug + ".md" : s.Replace($"{Path.DirectorySeparatorChar}index.md", ".md");
@@ -202,7 +207,8 @@ private static async Task<IResult> ServeDocumentationFile(ReloadableGeneratorSta
 		{
 			case MarkdownFile markdown:
 				var rendered = await generator.RenderLayout(markdown, ctx);
-				return Results.Content(rendered, "text/html");
+				return Results.Content(isNavPartial ? rendered.FullNavigationPartialHtml : rendered.Html, "text/html");
+
 			case ImageFile image:
 				return Results.File(image.SourceFile.FullName, image.MimeType);
 			default:
@@ -216,7 +222,7 @@ private static async Task<IResult> ServeDocumentationFile(ReloadableGeneratorSta
 					return Results.NotFound();
 
 				var renderedNotFound = await generator.RenderLayout((notFoundDocumentationFile as MarkdownFile)!, ctx);
-				return Results.Content(renderedNotFound, "text/html", null, (int)HttpStatusCode.NotFound);
+				return Results.Content(renderedNotFound.Html, "text/html", null, (int)HttpStatusCode.NotFound);
 		}
 	}
 }

Original file line number	Diff line number	Diff line change
`@@ -288,7 +288,7 @@ private async Task<IFileInfo> Render<T>(INavigationItem current, T page, ApiRend`
`288`	`288`	`if (!outputFile.Directory!.Exists)`
`289`	`289`	`outputFile.Directory.Create();`
`290`	`290`
`291`		`- var navigationHtml = await navigationRenderer.RenderNavigation(current.NavigationRoot, new Uri("http://ignored.example"), ctx);`
	`291`	`+ var navigationHtml = await navigationRenderer.RenderNavigation(current.NavigationRoot, new Uri("http://ignored.example"), INavigationHtmlWriter.AllLevels, ctx);`
`292`	`292`	`renderContext = renderContext with`
`293`	`293`	`{`
`294`	`294`	`CurrentNavigation = current,`
Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,12 @@ public bool PrimaryNavEnabled`
`20`	`20`	`set => _featureFlags["primary-nav"] = value;`
`21`	`21`	`}`
`22`	`22`
	`23`	`+ public bool LazyLoadNavigation`
	`24`	`+ {`
	`25`	`+ get => IsEnabled("LAZY_LOAD_NAVIGATION");`
	`26`	`+ set => _featureFlags["LAZY_LOAD_NAVIGATION"] = value;`
	`27`	`+ }`
	`28`	`+`
`23`	`29`	`private bool IsEnabled(string key)`
`24`	`30`	`{`
`25`	`31`	`var envKey = $"FEATURE_{key.ToUpperInvariant().Replace('-', '_')}";`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,9 @@ namespace Elastic.Documentation.Site.Navigation;`
`8`	`8`
`9`	`9`	`public interface INavigationHtmlWriter`
`10`	`10`	`{`
`11`		`- Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, Cancel ctx = default);`
	`11`	`+ const int AllLevels = -1;`
	`12`	`+`
	`13`	`+ Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, int maxLevel, Cancel ctx = default);`
`12`	`14`
`13`	`15`	`async Task<string> Render(NavigationViewModel model, Cancel ctx)`
`14`	`16`	`{`
Original file line number	Diff line number	Diff line change
`@@ -12,4 +12,6 @@ public class NavigationTreeItem`
`12`	`12`	`public required bool IsPrimaryNavEnabled { get; init; }`
`13`	`13`	`public required bool IsGlobalAssemblyBuild { get; init; }`
`14`	`14`	`public required string RootNavigationId { get; set; }`
	`15`	`+ // How many levels to render. Default is -1 (all levels)`
	`16`	`+ public required int MaxLevel { get; init; }`
`15`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,4 +15,7 @@ public class NavigationViewModel`
`15`	`15`
`16`	`16`	`/// controls whether to split the navigation tree automatically`
`17`	`17`	`public required bool IsUsingNavigationDropdown { get; init; }`
	`18`	`+`
	`19`	`+ // How many levels to render. -1 means all`
	`20`	`+ public required int MaxLevel { get; init; }`
`18`	`21`	`}`
Original file line number	Diff line number	Diff line change
`@@ -334,7 +334,7 @@ private async Task GenerateDocumentationState(Cancel ctx)`
`334`	`334`	`await DocumentationSet.OutputDirectory.FileSystem.File.WriteAllBytesAsync(stateFile.FullName, bytes, ctx);`
`335`	`335`	`}`
`336`	`336`
`337`		`- public async Task<string?> RenderLayout(MarkdownFile markdown, Cancel ctx)`
	`337`	`+ public async Task<RenderResult> RenderLayout(MarkdownFile markdown, Cancel ctx)`
`338`	`338`	`{`
`339`	`339`	`await DocumentationSet.Tree.Resolve(ctx);`
`340`	`340`	`return await HtmlWriter.RenderLayout(markdown, ctx);`