From 33282063f02ead236482667c7087ec0b3541b86d Mon Sep 17 00:00:00 2001
From: Martijn Laarman <Mpdreamz@gmail.com>
Date: Mon, 1 Jun 2026 15:13:50 +0200
Subject: [PATCH] perf(nav): reduce HTML output size by ~34% per page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Navigation HTML is embedded verbatim in every generated page, making
per-nav-item byte cost multiply across pages × nav items. At assembler
scale (69 repos, ~20k+ pages) this dominated the S3 upload volume.

Changes:
- Hoist hx-select-oob + preload from every nav anchor onto the two
  parent <ul> elements (#nav-tree, dropdown <ul>); htmx 2.0 inherits
  them, saving ~55 chars × nav item count per page
- Replace inline SVG chevron (336 chars) with <symbol>/<use> pattern;
  symbol defined once in _GlobalLayout, each folder toggle drops to
  ~40 chars
- Extract repeated Tailwind utility strings into named CSS component
  classes: .nav-link, .nav-folder-link, .nav-folder, .nav-toggle-btn,
  .nav-chevron, .nav-badge, .nav-badge-{ns,cmd,alias}, .nav-subtree
- Remove inline badge style constants from template; move colours into
  @layer components (immune to Tailwind purge, unlike arbitrary strings)
- Fix double-space bug in folder link class from empty isTopLevel branch

Measured on local isolated build (1,472 pages):
  Before: 558 MB raw HTML  →  After: 370 MB  (−33.8%, −128 KB/page)

Projected assembler impact: ~3–4 GB off the 11 GB S3 upload.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../Assets/styles.css                         | 66 ++++++++++++++++++
 .../Navigation/_TocTree.cshtml                |  8 +--
 .../Navigation/_TocTreeNav.cshtml             | 67 +++++--------------
 .../_GlobalLayout.cshtml                      |  7 ++
 4 files changed, 94 insertions(+), 54 deletions(-)

diff --git a/src/Elastic.Documentation.Site/Assets/styles.css b/src/Elastic.Documentation.Site/Assets/styles.css
index 27404ef2bb..ebb52e75c1 100644
--- a/src/Elastic.Documentation.Site/Assets/styles.css
+++ b/src/Elastic.Documentation.Site/Assets/styles.css
@@ -125,6 +125,72 @@ body {
 		}
 	}
 
+	.nav-badge {
+		@apply ml-auto inline-flex shrink-0 items-center rounded px-1.5 py-0.5 text-[9px] font-bold;
+	}
+
+	.nav-badge-ns {
+		background: #f5f3ff;
+		color: #7c3aed;
+		border: 1px solid #ddd6fe;
+	}
+
+	.nav-badge-cmd {
+		background: #fffbeb;
+		color: #b45309;
+		border: 1px solid #fde68a;
+	}
+
+	.nav-badge-alias {
+		background: #f0f9ff;
+		color: #0369a1;
+		border: 1px solid #bae6fd;
+	}
+
+	.nav-link {
+		@apply group-[.current]/li:text-blue-elastic! flex w-full grow items-center;
+	}
+
+	.nav-folder-link {
+		@apply group-[.current]/li:text-blue-elastic! flex content-center items-center gap-1 pr-2;
+	}
+
+	.nav-folder {
+		@apply relative flex flex-wrap;
+	}
+
+	.nav-toggle-btn {
+		@apply hover:bg-grey-20 cursor-pointer rounded-sm p-1;
+	}
+
+	.nav-chevron {
+		@apply w-3.5 shrink-0 -rotate-90 group-has-checked/label:rotate-0;
+		fill: none;
+		stroke-width: 1.5;
+		stroke: currentColor;
+	}
+
+	.nav-subtree {
+		@apply relative ml-4 hidden w-full;
+
+		/* revealed when the sibling .peer div contains a checked checkbox */
+		.peer:has(:checked) ~ & {
+			display: block;
+		}
+
+		&::before {
+			content: '';
+			@apply bg-grey-20 absolute top-0 bottom-0 w-px;
+			left: calc(var(--spacing) * -4 + 1px);
+		}
+
+		/* darken connector line when subtree contains the current page */
+		&:has(.current)::before,
+		.peer:has(.current) ~ &::before {
+			@apply bg-grey-40;
+		}
+	}
+
 	.sidebar-trial-card {
 		background: var(--color-green-30);
 		border-radius: 8px;
diff --git a/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml b/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml
index 3a83d7b8b6..60b45821cd 100644
--- a/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml
+++ b/src/Elastic.Documentation.Site/Navigation/_TocTree.cshtml
@@ -38,14 +38,14 @@
 							</div>
 						</button>
 					<div class="hidden group-focus-within:block left-0 right-0 absolute top-full">
-						<ul class="mt-1 py-2 bg-white border-1 border-grey-20 rounded-sm shadow-md">
+						<ul class="mt-1 py-2 bg-white border-1 border-grey-20 rounded-sm shadow-md"
+						@Model.Htmx.GetNavHxAttributes(false, "mouseover")>
 				@foreach (var item in Model.TopLevelItems)
 				{
 								<li class="block">
 									<a
 										class="block py-2 px-4 hover:underline hover:text-black hover:bg-grey-10 active:bg-blue-elastic-70 active:text-white font-semibold @(item.NavigationRoot.Id == Model.Tree.Id ? "text-blue-elastic" : "")"
-										href="@item.Url"
-										@Model.Htmx.GetNavHxAttributes(false, "mouseover")>
+										href="@item.Url">
 							@item.NavigationTitle
 						</a>
 					</li>
@@ -62,7 +62,7 @@
 		</div>
 	</div>
 
-	<ul class="block px-4" id="nav-tree">
+	<ul class="block px-4" id="nav-tree" @Model.Htmx.GetNavHxAttributes(true)>
 		@await RenderPartialAsync(_TocTreeNav.Create(new NavigationTreeItem
 		{
 			IsPrimaryNavEnabled = Model.IsPrimaryNavEnabled,
diff --git a/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml b/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml
index 40d981dbb6..868232d732 100644
--- a/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml
+++ b/src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml
@@ -14,25 +14,12 @@
 		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 AliasStyle = "background:#f0f9ff;color:#0369a1;border:1px solid #bae6fd;";
-
-	static string BadgeStyle(string? badge) => badge switch { "ns" => NsStyle, "cmd" => CmdStyle, "alias" => AliasStyle, _ => "" };
 }
 @if (isTopLevel && !Model.IsGlobalAssemblyBuild && !Model.IsPrimaryNavEnabled && !Model.SubTree.Index.Hidden)
 {
 	var idx = Model.SubTree.Index;
 	<li class="flex group/li pr-8 mt-6">
-		<a
-			href="@idx.Url"
-			@Model.Htmx.GetNavHxAttributes(true)
-			class="sidebar-link grow group-[.current]/li:text-blue-elastic!"
-		>
-			@idx.NavigationTitle
-		</a>
+		<a href="@idx.Url" class="sidebar-link nav-link">@idx.NavigationTitle</a>
 	</li>
 }
 @foreach (var item in Model.SubTree.NavigationItems)
@@ -50,15 +37,11 @@
 	{
 		var (groupBadge, groupLabel) = ParseNavTitle(group.NavigationTitle);
 		<li class="flex group/li pr-8 @(isTopLevel ? "font-semibold mt-6" : "mt-4")">
-			<a
-				href="@group.Url"
-				@Model.Htmx.GetNavHxAttributes(true)
-				class="sidebar-link group-[.current]/li:text-blue-elastic! flex items-center w-full"
-			>
+			<a href="@group.Url" class="sidebar-link nav-link">
 				<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> }
+				@if (groupBadge == "ns") { <span class="nav-badge nav-badge-ns">ns</span> }
+				else if (groupBadge == "cmd") { <span class="nav-badge nav-badge-cmd">cmd</span> }
+				else if (groupBadge == "alias") { <span class="nav-badge nav-badge-alias">alias</span> }
 			</a>
 		</li>
 	}
@@ -67,30 +50,19 @@
 		var g = folder;
 		var allHidden = folder.NavigationItems.All(n => n.Hidden);
 		var (folderBadge, folderLabel) = ParseNavTitle(g.NavigationTitle);
-		<li class="flex flex-wrap group-navigation @(isTopLevel ? "mt-6" : "mt-4") relative">
+		<li class="nav-folder @(isTopLevel ? "mt-6" : "mt-4")">
 			<div class="peer grid grid-cols-[1fr_auto] w-full">
-				<a
-					href="@(g.Url)"
-					@Model.Htmx.GetNavHxAttributes(true)
-					class="sidebar-link pr-2 content-center @(isTopLevel ? "font-semibold" : "") group-[.current]/li:text-blue-elastic! flex items-center gap-1">
+				<a href="@(g.Url)" class="sidebar-link nav-folder-link@(isTopLevel ? " font-semibold" : "")">
 					<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> }
+					@if (folderBadge == "ns") { <span class="nav-badge nav-badge-ns">ns</span> }
+					else if (folderBadge == "cmd") { <span class="nav-badge nav-badge-cmd">cmd</span> }
+					else if (folderBadge == "alias") { <span class="nav-badge nav-badge-alias">alias</span> }
 				</a>
 				@if (!allHidden)
 				{
 					<label for="@folder.Id" class="group/label flex mr-2 items-start">
-						<div class="hover:bg-grey-20 rounded-sm p-1 cursor-pointer">
-							<svg
-								xmlns="http://www.w3.org/2000/svg"
-								fill="none"
-								viewBox="0 0 24 24"
-								stroke-width="1.5"
-								stroke="currentColor"
-								class="shrink-0 -rotate-90 group-has-checked/label:rotate-0 w-3.5">
-								<path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/>
-							</svg>
+						<div class="nav-toggle-btn">
+							<svg class="nav-chevron" viewBox="0 0 24 24"><use href="#icon-chevron-down"/></svg>
 						</div>
 						<input
 							id="@folder.Id"
@@ -102,7 +74,7 @@
 			</div>
 			@if (g.NavigationItems.Count > 0)
 			{
-				<ul class="w-full hidden peer-has-checked:block ml-4 relative before:content-[''] before:absolute before:-left-[calc(var(--spacing)*4-1px)] before:top-0 before:bottom-0 before:w-px before:bg-grey-20 before:peer-has-checked:block peer-has-[.current]:before:bg-grey-40 has-[.current]:before:bg-grey-40">
+				<ul class="nav-subtree">
 					@await RenderPartialAsync(_TocTreeNav.Create(new NavigationTreeItem
 					{
 						IsPrimaryNavEnabled = Model.IsPrimaryNavEnabled,
@@ -118,18 +90,13 @@
 	}
 	else if (item is ILeafNavigationItem<INavigationModel> leaf)
 	{
-		var hasSameTopLevelGroup = true;
 		var (leafBadge, leafLabel) = ParseNavTitle(leaf.NavigationTitle);
 		<li class="flex group/li pr-8 @(isTopLevel ? "font-semibold mt-6" : "mt-4")">
-			<a
-				href="@leaf.Url"
-				@Model.Htmx.GetNavHxAttributes(hasSameTopLevelGroup)
-				class="sidebar-link grow group-[.current]/li:text-blue-elastic! flex items-center w-full"
-			>
+			<a href="@leaf.Url" class="sidebar-link nav-link">
 				<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> }
+				@if (leafBadge == "ns") { <span class="nav-badge nav-badge-ns">ns</span> }
+				else if (leafBadge == "cmd") { <span class="nav-badge nav-badge-cmd">cmd</span> }
+				else if (leafBadge == "alias") { <span class="nav-badge nav-badge-alias">alias</span> }
 			</a>
 		</li>
 	}
diff --git a/src/Elastic.Documentation.Site/_GlobalLayout.cshtml b/src/Elastic.Documentation.Site/_GlobalLayout.cshtml
index 8084c89ebd..d2e300e661 100644
--- a/src/Elastic.Documentation.Site/_GlobalLayout.cshtml
+++ b/src/Elastic.Documentation.Site/_GlobalLayout.cshtml
@@ -15,6 +15,13 @@
 	data-root-path="@(Model.Htmx.GetRootPath())"
 	hx-boost="true" hx-swap="none" hx-push-url="true" hx-indicator="#htmx-indicator"
 	>
+<svg xmlns="http://www.w3.org/2000/svg" class="hidden" aria-hidden="true">
+	<defs>
+		<symbol id="icon-chevron-down" viewBox="0 0 24 24">
+			<path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/>
+		</symbol>
+	</defs>
+</svg>
 @if (Model.GoogleTagManager.Enabled)
 {
 	<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=@(Model.GoogleTagManager.Id)@(new HtmlString(Model.GoogleTagManager.QueryString()))"