From bc3a153e21403e6e252e609ac040b8fd21418b9c Mon Sep 17 00:00:00 2001
From: Jan Calanog <jan.calanog@elastic.co>
Date: Wed, 2 Jul 2025 15:49:27 +0200
Subject: [PATCH 1/3] PoC: Lazy loaded navigation

---
 src/Elastic.ApiExplorer/OpenApiGenerator.cs   |  2 +-
 .../Layout/_PagesNav.cshtml                   |  1 +
 .../Navigation/INavigationHtmlWriter.cs       |  2 +-
 .../IsolatedBuildNavigationHtmlWriter.cs      | 15 ++++++-------
 .../Navigation/NavigationTreeItem.cs          |  2 ++
 .../Navigation/NavigationViewModel.cs         |  3 +++
 .../Navigation/_TocTree.cshtml                |  2 ++
 .../Navigation/_TocTreeNav.cshtml             | 21 ++++++++++++-------
 .../DocumentationGenerator.cs                 |  2 +-
 src/Elastic.Markdown/HtmlWriter.cs            | 16 +++++++-------
 .../Navigation/GlobalNavigationHtmlWriter.cs  | 17 ++++++++-------
 .../docs-builder/Http/DocumentationWebHost.cs | 12 ++++++++---
 12 files changed, 60 insertions(+), 35 deletions(-)

diff --git a/src/Elastic.ApiExplorer/OpenApiGenerator.cs b/src/Elastic.ApiExplorer/OpenApiGenerator.cs
index 75e9129bc..568cfc71a 100644
--- 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"), -1, ctx);
 		renderContext = renderContext with
 		{
 			CurrentNavigation = current,
diff --git a/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml b/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
index 8b95f7e69..60cc57e38 100644
--- a/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
+++ b/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
@@ -1,5 +1,6 @@
 @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">
+	<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
index f824d2074..df1a2fff8 100644
--- a/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
+++ b/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
@@ -8,7 +8,7 @@ namespace Elastic.Documentation.Site.Navigation;
 
 public interface INavigationHtmlWriter
 {
-	Task<string> RenderNavigation(IRootNavigationItem<INavigationModel, INavigationItem> currentRootNavigation, Uri navigationSource, Cancel ctx = default);
+	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
index 7c89b8755..1b7f9ac25 100644
--- 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
index 8e689111e..8d05df7ca 100644
--- 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
index bb4df6ad5..0c21cf7a0 100644
--- 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
index fc8b2c12d..3ce85b96a 100644
--- 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
index 4c72a92d9..19fe3e250 100644
--- 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
index 841bbb171..078d1ef5d 100644
--- 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<(string, string)> 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
index 21c9fcf83..66614b078 100644
--- a/src/Elastic.Markdown/HtmlWriter.cs
+++ b/src/Elastic.Markdown/HtmlWriter.cs
@@ -44,18 +44,19 @@ public string Render(string markdown, IFileInfo? source)
 		return MarkdownFile.CreateHtml(parsed);
 	}
 
-	public async Task<string> RenderLayout(MarkdownFile markdown, Cancel ctx = default)
+	public async Task<(string, string)> 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<(string, string)> 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, -1, ctx);
+		var miniNavigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, 1, ctx);
 
 		var current = PositionalNavigation.GetCurrent(markdown);
 		var previous = PositionalNavigation.GetPrevious(markdown);
@@ -115,7 +116,7 @@ private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument
 			PreviousDocument = previous,
 			NextDocument = next,
 			Parents = parents,
-			NavigationHtml = navigationHtml,
+			NavigationHtml = miniNavigationHtml,
 			UrlPathPrefix = markdown.UrlPathPrefix,
 			AppliesTo = markdown.YamlFrontMatter?.AppliesTo,
 			GithubEditUrl = editUrl,
@@ -132,7 +133,7 @@ private async Task<string> RenderLayout(MarkdownFile markdown, MarkdownDocument
 			Products = allProducts,
 			VersionsConfig = DocumentationSet.Context.VersionsConfig
 		});
-		return await slice.RenderAsync(cancellationToken: ctx);
+		return (fullNavigationHtml, await slice.RenderAsync(cancellationToken: ctx));
 	}
 
 	public async Task<MarkdownDocument> WriteAsync(IFileInfo outputFile, MarkdownFile markdown, IConversionCollector? collector, Cancel ctx = default)
@@ -160,8 +161,9 @@ 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.Item2);
+		await writeFileSystem.File.WriteAllTextAsync(path, rendered.Item2, ctx);
+		await writeFileSystem.File.WriteAllTextAsync(path.Replace(".html", ".nav.html"), rendered.Item1, ctx);
 		return document;
 	}
 
diff --git a/src/tooling/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs b/src/tooling/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs
index 1825a726c..4ea22701f 100644
--- 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-builder/Http/DocumentationWebHost.cs b/src/tooling/docs-builder/Http/DocumentationWebHost.cs
index ad21644f5..5bcd69bc3 100644
--- 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.Item1 : rendered.Item2, "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.Item2, "text/html", null, (int)HttpStatusCode.NotFound);
 		}
 	}
 }

From 23b38d76fa08e2c184e207033bfab68f2a488a83 Mon Sep 17 00:00:00 2001
From: Jan Calanog <jan.calanog@elastic.co>
Date: Wed, 2 Jul 2025 16:10:02 +0200
Subject: [PATCH 2/3] Hide functionality behind the LAZY_LOAD_NAVIGATION
 feature flag

---
 .../Builder/FeatureFlags.cs                   |  6 ++++
 .../Layout/_PagesNav.cshtml                   |  6 +++-
 .../DocumentationGenerator.cs                 |  2 +-
 src/Elastic.Markdown/HtmlWriter.cs            | 33 ++++++++++++++-----
 src/tooling/docs-assembler/assembler.yml      |  2 ++
 .../docs-builder/Http/DocumentationWebHost.cs |  4 +--
 6 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs
index 6d54f808b..1ae0ddbc3 100644
--- 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
index 60cc57e38..baec6f8de 100644
--- a/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
+++ b/src/Elastic.Documentation.Site/Layout/_PagesNav.cshtml
@@ -1,6 +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">
-	<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>
+	
+	@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.Markdown/DocumentationGenerator.cs b/src/Elastic.Markdown/DocumentationGenerator.cs
index 078d1ef5d..e80af4519 100644
--- 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, 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
index 66614b078..848364e55 100644
--- a/src/Elastic.Markdown/HtmlWriter.cs
+++ b/src/Elastic.Markdown/HtmlWriter.cs
@@ -44,19 +44,21 @@ public string Render(string markdown, IFileInfo? source)
 		return MarkdownFile.CreateHtml(parsed);
 	}
 
-	public async Task<(string, 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, 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 fullNavigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, -1, ctx);
-		var miniNavigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, 1, 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);
@@ -116,7 +118,7 @@ public string Render(string markdown, IFileInfo? source)
 			PreviousDocument = previous,
 			NextDocument = next,
 			Parents = parents,
-			NavigationHtml = miniNavigationHtml,
+			NavigationHtml = DocumentationSet.Configuration.Features.LazyLoadNavigation ? miniNavigationHtml : fullNavigationHtml,
 			UrlPathPrefix = markdown.UrlPathPrefix,
 			AppliesTo = markdown.YamlFrontMatter?.AppliesTo,
 			GithubEditUrl = editUrl,
@@ -133,7 +135,12 @@ public string Render(string markdown, IFileInfo? source)
 			Products = allProducts,
 			VersionsConfig = DocumentationSet.Context.VersionsConfig
 		});
-		return (fullNavigationHtml, 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)
@@ -161,10 +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.Item2);
-		await writeFileSystem.File.WriteAllTextAsync(path, rendered.Item2, ctx);
-		await writeFileSystem.File.WriteAllTextAsync(path.Replace(".html", ".nav.html"), rendered.Item1, 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/assembler.yml b/src/tooling/docs-assembler/assembler.yml
index 472c5a723..eceb4402a 100644
--- 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
index 5bcd69bc3..79776f616 100644
--- a/src/tooling/docs-builder/Http/DocumentationWebHost.cs
+++ b/src/tooling/docs-builder/Http/DocumentationWebHost.cs
@@ -207,7 +207,7 @@ private static async Task<IResult> ServeDocumentationFile(ReloadableGeneratorSta
 		{
 			case MarkdownFile markdown:
 				var rendered = await generator.RenderLayout(markdown, ctx);
-				return Results.Content(isNavPartial ? rendered.Item1 : rendered.Item2, "text/html");
+				return Results.Content(isNavPartial ? rendered.FullNavigationPartialHtml : rendered.Html, "text/html");
 
 			case ImageFile image:
 				return Results.File(image.SourceFile.FullName, image.MimeType);
@@ -222,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.Item2, "text/html", null, (int)HttpStatusCode.NotFound);
+				return Results.Content(renderedNotFound.Html, "text/html", null, (int)HttpStatusCode.NotFound);
 		}
 	}
 }

From da12dce0f28582007ae94441999f665a469b007b Mon Sep 17 00:00:00 2001
From: Jan Calanog <jan.calanog@elastic.co>
Date: Wed, 2 Jul 2025 16:30:49 +0200
Subject: [PATCH 3/3] Refactor

---
 src/Elastic.ApiExplorer/OpenApiGenerator.cs                     | 2 +-
 .../Navigation/INavigationHtmlWriter.cs                         | 2 ++
 src/Elastic.Markdown/HtmlWriter.cs                              | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/Elastic.ApiExplorer/OpenApiGenerator.cs b/src/Elastic.ApiExplorer/OpenApiGenerator.cs
index 568cfc71a..66dab39cc 100644
--- 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"), -1, 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.Site/Navigation/INavigationHtmlWriter.cs b/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
index df1a2fff8..c1ac29df8 100644
--- a/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
+++ b/src/Elastic.Documentation.Site/Navigation/INavigationHtmlWriter.cs
@@ -8,6 +8,8 @@ namespace Elastic.Documentation.Site.Navigation;
 
 public interface INavigationHtmlWriter
 {
+	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.Markdown/HtmlWriter.cs b/src/Elastic.Markdown/HtmlWriter.cs
index 848364e55..fb1e7aaa1 100644
--- a/src/Elastic.Markdown/HtmlWriter.cs
+++ b/src/Elastic.Markdown/HtmlWriter.cs
@@ -55,7 +55,7 @@ private async Task<RenderResult> RenderLayout(MarkdownFile markdown, MarkdownDoc
 		var html = MarkdownFile.CreateHtml(document);
 		await DocumentationSet.Tree.Resolve(ctx);
 
-		var fullNavigationHtml = await NavigationHtmlWriter.RenderNavigation(markdown.NavigationRoot, markdown.NavigationSource, -1, 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";