From ba425e96808b5a5feb531185a1a0ec65108cc7dd Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Tue, 8 Sep 2026 22:29:22 +0200
Subject: [PATCH 01/18] Match Mintlify accordion styling

---
 src/components/compat/Accordion.astro | 106 +++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 2 deletions(-)

diff --git a/src/components/compat/Accordion.astro b/src/components/compat/Accordion.astro
index 1e320c925..98e61b5f9 100644
--- a/src/components/compat/Accordion.astro
+++ b/src/components/compat/Accordion.astro
@@ -6,8 +6,110 @@ const { title, description, defaultOpen } = Astro.props;
 
 <details class="ch-accordion" open={defaultOpen}>
   <summary>
-    <span class="ch-accordion-title">{title}</span>
-    {description && <span class="ch-accordion-description">{description}</span>}
+    <span class="ch-accordion-caret" aria-hidden="true">
+      <svg width="18" height="18" viewBox="0 0 18 18" fill="currentColor">
+        <path d="M14.0238 4.00002H3.97576C3.33776 4.00002 2.74976 4.34702 2.44276 4.90602C2.13576 5.46502 2.15576 6.14802 2.49776 6.68702L7.52176 14.61C7.84476 15.119 8.39676 15.422 8.99976 15.422C9.60276 15.422 10.1548 15.118 10.4778 14.61L15.5028 6.68602C15.8438 6.14702 15.8648 5.46402 15.5578 4.90502C15.2508 4.34602 14.6628 3.99902 14.0248 3.99902L14.0238 4.00002Z" />
+      </svg>
+    </span>
+    <span class="ch-accordion-copy">
+      <span class="ch-accordion-title">{title}</span>
+      {description && <span class="ch-accordion-description">{description}</span>}
+    </span>
   </summary>
   <div class="ch-accordion-body"><slot /></div>
 </details>
+
+<style>
+  .ch-accordion {
+    margin: 0 0 12px;
+    overflow: hidden;
+    border: 1px solid rgb(28 28 28 / 10%);
+    border-radius: 4px;
+    background: #fff;
+  }
+
+  .ch-accordion summary {
+    min-height: 52px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 14px 20px;
+    color: var(--nb-heading);
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .ch-accordion summary:hover {
+    background: rgb(28 28 28 / 5%);
+  }
+
+  .ch-accordion summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .ch-accordion summary::marker {
+    content: "";
+  }
+
+  .ch-accordion-caret {
+    width: 16px;
+    height: 16px;
+    display: flex;
+    flex: 0 0 16px;
+    align-items: center;
+    justify-content: center;
+    color: var(--nb-muted-foreground);
+  }
+
+  .ch-accordion-caret svg {
+    width: 12px;
+    height: 12px;
+    transform: rotate(-90deg);
+    transition: transform 200ms ease;
+  }
+
+  .ch-accordion[open] .ch-accordion-caret svg {
+    transform: rotate(0deg);
+  }
+
+  .ch-accordion-copy {
+    min-width: 0;
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    text-align: left;
+  }
+
+  .ch-accordion-title {
+    margin: 0;
+    font-size: 16px;
+    font-weight: 500;
+    line-height: 24px;
+  }
+
+  .ch-accordion-description {
+    color: var(--nb-muted-foreground);
+    font-size: 14px;
+    line-height: 20px;
+  }
+
+  .ch-accordion-body {
+    overflow-x: auto;
+    padding: 0 20px 14px;
+  }
+
+  :global([data-mode="dark"]) .ch-accordion {
+    border-color: #3c3c3c;
+    background: #242424;
+  }
+
+  :global([data-mode="dark"]) .ch-accordion summary:hover {
+    background: #2a2a2a;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ch-accordion-caret svg {
+      transition: none;
+    }
+  }
+</style>

From 4b082088985a6fc87b0063092c4af22e2e5c0c3f Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Tue, 8 Sep 2026 22:43:05 +0200
Subject: [PATCH 02/18] Add spacing before accordions

---
 src/components/compat/Accordion.astro | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/components/compat/Accordion.astro b/src/components/compat/Accordion.astro
index 98e61b5f9..abd448273 100644
--- a/src/components/compat/Accordion.astro
+++ b/src/components/compat/Accordion.astro
@@ -21,13 +21,17 @@ const { title, description, defaultOpen } = Astro.props;
 
 <style>
   .ch-accordion {
-    margin: 0 0 12px;
+    margin: 20px 0 12px;
     overflow: hidden;
     border: 1px solid rgb(28 28 28 / 10%);
     border-radius: 4px;
     background: #fff;
   }
 
+  .ch-accordion + .ch-accordion {
+    margin-top: 0;
+  }
+
   .ch-accordion summary {
     min-height: 52px;
     display: flex;

From d2a8557c4084048dac944d5b5c190b0aaf86ae54 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Tue, 8 Sep 2026 22:44:43 +0200
Subject: [PATCH 03/18] Reduce sidebar language selector height

---
 src/styles/globals.css | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/styles/globals.css b/src/styles/globals.css
index 73dd34b24..5f6533fd9 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -1269,14 +1269,14 @@ body:not(:has([data-mobile-sidebar])) [data-menu-btn] {
 
 .ch-language-selector {
 	position: relative;
-	height: 58px;
+	height: 48px;
 	flex: 0 0 auto;
 	border-top: 1px solid var(--nb-border);
 }
 
 .ch-language-selector-trigger {
 	width: 100%;
-	height: 57px;
+	height: 47px;
 	display: flex;
 	align-items: center;
 	gap: 8px;
@@ -1307,7 +1307,7 @@ body:not(:has([data-mobile-sidebar])) [data-menu-btn] {
 	position: absolute;
 	z-index: 80;
 	right: 16px;
-	bottom: 54px;
+	bottom: 44px;
 	left: 16px;
 	max-height: min(430px, calc(100vh - 170px));
 	overflow: auto;

From d6066c644faeb13097dfb4d423fc7ad22b01cecc Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Tue, 8 Sep 2026 23:25:45 +0200
Subject: [PATCH 04/18] Bake documentation icons into builds

---
 _site/customizations/kapa-init.js     |  4 +-
 _site/styles.css                      |  5 --
 package.json                          |  1 +
 pnpm-lock.yaml                        | 10 +++
 src/components/compat/Card.astro      | 26 ++++---
 src/components/ui/tabs/TabItem.astro  | 22 ++++--
 src/components/ui/tabs/Tabs.astro     | 99 ++++++++++++++++++++++++++-
 src/components/ui/tabs/tabs.client.ts | 23 +------
 src/layouts/BaseLayout.astro          |  4 +-
 src/lib/build-icon.ts                 | 41 +++++++++++
 src/lib/tab-id.ts                     |  8 +++
 src/styles/globals.css                | 11 ---
 12 files changed, 199 insertions(+), 55 deletions(-)
 create mode 100644 src/lib/build-icon.ts
 create mode 100644 src/lib/tab-id.ts

diff --git a/_site/customizations/kapa-init.js b/_site/customizations/kapa-init.js
index 4974b29db..d8258ffff 100644
--- a/_site/customizations/kapa-init.js
+++ b/_site/customizations/kapa-init.js
@@ -54,7 +54,7 @@
       'data-website-id': '5df6cc2b-732e-44e4-b789-aec81b70fe46',
       'data-project-name': 'ClickHouse',
       'data-project-color': '#151515',
-      'data-project-logo': 'https://avatars.githubusercontent.com/u/54801242?s=200&v=4',
+      'data-project-logo': '/docs/images/logo.svg',
       'data-modal-disclaimer': 'This is a custom LLM for ClickHouse with access to all developer documentation, open GitHub Issues, YouTube videos, and resolved StackOverflow posts. Please note that answers are generated by AI and may not be fully accurate, so please use your best judgement.',
       'data-modal-example-questions': 'How to speed up queries?,How to use materialized views?',
       // Disable the MCP install dropdown/tab in the Kapa widget header.
@@ -80,4 +80,4 @@
       console.log('An error occurred while trying to load the Kapa.ai widget:', e);
     }
   }
-})();
\ No newline at end of file
+})();
diff --git a/_site/styles.css b/_site/styles.css
index 84e2a46b3..846a7bb1b 100644
--- a/_site/styles.css
+++ b/_site/styles.css
@@ -1715,11 +1715,6 @@ button.rounded-xl {
    ClickPipes Page Styling
    ============================================ */
 
-/* Dark mode image swap for ClickPipes icons */
-:is(.dark) .product-item img[src*="clickpipes-light.svg"] {
-    content: url("https://ch-docs-product-selector.s3.eu-central-1.amazonaws.com/clickpipes-dark.svg") !important;
-}
-
 /* Kafka nav-group icon is a solid black SVG (fill:#000); invert it to white in
    dark mode so it doesn't disappear against the dark sidebar. Single asset, no
    light/dark swap. */
diff --git a/package.json b/package.json
index b3cfe950c..111130e9b 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,7 @@
     "@cloudflare/nimbus-docs": "0.12.0",
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
+    "@iconify-json/fa6-brands": "^1.2.6",
     "@iconify-json/fa6-solid": "^1.2.4",
     "@iconify-json/ph": "^1.2.0",
     "@inkeep/cxkit-react": "^0.5.119",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 06fcd966e..9e842539c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -23,6 +23,9 @@ importers:
       '@fontsource-variable/jetbrains-mono':
         specifier: ^5.2.8
         version: 5.3.0
+      '@iconify-json/fa6-brands':
+        specifier: ^1.2.6
+        version: 1.2.6
       '@iconify-json/fa6-solid':
         specifier: ^1.2.4
         version: 1.2.4
@@ -895,6 +898,9 @@ packages:
   '@fontsource-variable/jetbrains-mono@5.3.0':
     resolution: {integrity: sha512-F32xpS2NsGYoQi2ADSkKTgpJj7ozajsGgDJ8woTnqjmIB+dxDIqImjl4pXZVEExu8UFZ2ndhmX18EBS/hdz3Lw==}
 
+  '@iconify-json/fa6-brands@1.2.6':
+    resolution: {integrity: sha512-twL3X4KWcxAhbc1vz/mIDsVr+CAItk1/EIfxKUVQtpv6O4eydk5KNYqTZWdvJNHGInUgd6vKg21aWfVgb5DXEg==}
+
   '@iconify-json/fa6-solid@1.2.4':
     resolution: {integrity: sha512-LmDNNdJVyvF5mPm1yxWvL8KjCc/E8LzoqnF1LNTVpyY2ZJRUlGOWuPIThdbuFBF2IovgttkIyumhyqfmlHdwKg==}
 
@@ -5776,6 +5782,10 @@ snapshots:
 
   '@fontsource-variable/jetbrains-mono@5.3.0': {}
 
+  '@iconify-json/fa6-brands@1.2.6':
+    dependencies:
+      '@iconify/types': 2.0.0
+
   '@iconify-json/fa6-solid@1.2.4':
     dependencies:
       '@iconify/types': 2.0.0
diff --git a/src/components/compat/Card.astro b/src/components/compat/Card.astro
index 9f3990866..4804989da 100644
--- a/src/components/compat/Card.astro
+++ b/src/components/compat/Card.astro
@@ -2,26 +2,33 @@
 /**
  * Mintlify `<Card title icon href horizontal img cta arrow>`. Renders Nimbus's
  * Card, wrapped in a link when `href` is set. Mintlify's named icons are
- * rendered with the same Font Awesome masks as the source site.
+ * resolved from local Iconify collections and inlined during the build.
  */
 import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";
-import { withBase } from "@/lib/base";
+import { inlinePublicIcon } from "@/lib/build-icon";
 interface Props { title?: string; icon?: string; href?: string; horizontal?: boolean; img?: string; cta?: string; arrow?: boolean; color?: string }
 const { title = "", href, img, cta, icon, horizontal: _h, arrow: _a, color: _c, ...rest } = Astro.props;
+if (icon?.startsWith("http://") || icon?.startsWith("https://")) {
+  throw new Error(`External card icon URLs are not supported: ${icon}`);
+}
 const isNamedMintlifyIcon = Boolean(icon && !icon.startsWith("/") && !icon.startsWith("http") && !icon.includes(":"));
-const iconName = isNamedMintlifyIcon ? undefined : icon;
-const iconIsImage = Boolean(iconName?.startsWith("/") || iconName?.startsWith("http"));
-const resolvedIconName = iconIsImage && iconName?.startsWith("/") ? withBase(iconName) : iconName;
-const mintlifyIconStyle = isNamedMintlifyIcon
-  ? `--ch-card-icon-mask:url("https://d3gk2c5xim1je2.cloudfront.net/fontawesome/v7.2.0/regular/${icon}.svg")`
-  : undefined;
+const brandIcons = new Set(["docker", "linux", "redhat", "ubuntu"]);
+const phosphorIcons = new Set(["browser", "function"]);
+const iconName = isNamedMintlifyIcon
+  ? brandIcons.has(icon!)
+    ? `fa6-brands:${icon}`
+    : phosphorIcons.has(icon!)
+      ? `ph:${icon}`
+      : `fa6-solid:${icon}`
+  : icon;
+const iconIsImage = Boolean(iconName?.startsWith("/") || iconName?.startsWith("data:"));
+const resolvedIconName = iconIsImage && iconName ? inlinePublicIcon(iconName) : iconName;
 ---
 
 {href ? (
   <a href={href} class="ch-card-link">
     <article class="ch-doc-card" {...rest}>
       {img && <img src={img} alt="" class="ch-card-img" />}
-      {isNamedMintlifyIcon && <span aria-hidden="true" class="ch-card-icon ch-card-icon-mask" style={mintlifyIconStyle}></span>}
       {resolvedIconName && (iconIsImage ? <img src={resolvedIconName} alt="" class="ch-card-icon" /> : <Icon name={resolvedIconName} class="ch-card-icon" />)}
       <h2>{title}</h2>
       <slot />
@@ -31,7 +38,6 @@ const mintlifyIconStyle = isNamedMintlifyIcon
 ) : (
   <article class="ch-doc-card" {...rest}>
     {img && <img src={img} alt="" class="ch-card-img" />}
-    {isNamedMintlifyIcon && <span aria-hidden="true" class="ch-card-icon ch-card-icon-mask" style={mintlifyIconStyle}></span>}
     {resolvedIconName && (iconIsImage ? <img src={resolvedIconName} alt="" class="ch-card-icon" /> : <Icon name={resolvedIconName} class="ch-card-icon" />)}
     <h2>{title}</h2>
     <slot />
diff --git a/src/components/ui/tabs/TabItem.astro b/src/components/ui/tabs/TabItem.astro
index b2704236c..aef09c8da 100644
--- a/src/components/ui/tabs/TabItem.astro
+++ b/src/components/ui/tabs/TabItem.astro
@@ -2,11 +2,11 @@
 /**
  * TabItem — single tab panel in the `<Tabs>` component.
  *
- * The `label` prop is read by `tabs.client.ts` to synthesize the matching
- * trigger button. Each TabItem becomes one `[data-nb-tabs-content]` panel.
+ * The parent `<Tabs>` reads the rendered metadata and emits the matching
+ * trigger into the initial HTML. Each TabItem becomes one panel.
  */
 import { cn } from "@/lib/cn";
-import { withBase } from "@/lib/base";
+import { inlinePublicIcon } from "@/lib/build-icon";
 import type { HTMLAttributes } from "astro/types";
 
 interface Props extends HTMLAttributes<"div"> {
@@ -20,13 +20,27 @@ const { label, icon, class: className, ...attrs } = Astro.props;
 if (!label) {
   throw new Error("Missing required `label` prop on `<TabItem>` component.");
 }
+
+const externalIconAliases: Record<string, string> = {
+  "https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/logo-windsurf.svg": "/images/logo-windsurf.svg",
+  "https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/logo-cursor.png": "/images/logo-cursor.webp",
+  "https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/logo-claudecode-color.svg": "/images/logo-claudecode-color.svg",
+  "https://clickhouse-docs-assets.s3.us-east-1.amazonaws.com/logo-claude.svg": "/images/logo-claude.svg",
+};
+const normalizedIcon = icon ? externalIconAliases[icon] ?? icon : undefined;
+const resolvedIcon = normalizedIcon?.startsWith("/") || normalizedIcon?.startsWith("data:")
+  ? inlinePublicIcon(normalizedIcon)
+  : normalizedIcon;
+if (resolvedIcon?.startsWith("http://") || resolvedIcon?.startsWith("https://")) {
+  throw new Error(`External tab icon URLs are not supported: ${resolvedIcon}`);
+}
 ---
 
 <div
   role="tabpanel"
   data-nb-tabs-content
   data-nb-tab-label={label}
-  data-nb-tab-icon={icon ? withBase(icon) : undefined}
+  data-nb-tab-icon={resolvedIcon}
   class={cn(className)}
   {...attrs}
 >
diff --git a/src/components/ui/tabs/Tabs.astro b/src/components/ui/tabs/Tabs.astro
index e5c356fa0..b633764d8 100644
--- a/src/components/ui/tabs/Tabs.astro
+++ b/src/components/ui/tabs/Tabs.astro
@@ -8,6 +8,8 @@
  * For manual control: TabsList, TabsTrigger, TabsContent.
  */
 import { cn } from "@/lib/cn";
+import { nextTabId } from "@/lib/tab-id";
+import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";
 import type { HTMLAttributes } from "astro/types";
 import TabsList from "./TabsList.astro";
 
@@ -17,6 +19,68 @@ interface Props extends HTMLAttributes<"div"> {
 }
 
 const { syncKey, class: className, ...attrs } = Astro.props;
+const tabsId = nextTabId(Astro.locals);
+
+let renderedContent = await Astro.slots.render("default");
+
+const decodeAttribute = (value: string) => value.replace(
+  /&(?:quot|amp|lt|gt|#39|#x[0-9a-f]+|#\d+);/gi,
+  (entity) => {
+    const named: Record<string, string> = {
+      "&quot;": '"', "&amp;": "&", "&lt;": "<", "&gt;": ">", "&#39;": "'",
+    };
+    const normalized = entity.toLowerCase();
+    if (named[normalized]) return named[normalized];
+    const numeric = normalized.startsWith("&#x")
+      ? Number.parseInt(normalized.slice(3, -1), 16)
+      : Number.parseInt(normalized.slice(2, -1), 10);
+    return Number.isFinite(numeric) ? String.fromCodePoint(numeric) : entity;
+  },
+);
+const readAttribute = (attributes: string, name: string) => {
+  const match = attributes.match(new RegExp(`(?:^|\\s)${name}="([^"]*)"`));
+  return match ? decodeAttribute(match[1] ?? "") : undefined;
+};
+
+const tabs: Array<{ label: string; icon?: string; panelId: string }> = [];
+let panelIndex = 0;
+let divDepth = 0;
+renderedContent = renderedContent.replace(
+  /<\/?div\b[^>]*>/g,
+  (tag) => {
+    if (tag.startsWith("</")) {
+      divDepth--;
+      return tag;
+    }
+
+    const isDirectPanel = divDepth === 0 && /\bdata-nb-tabs-content\b/.test(tag);
+    divDepth++;
+    if (!isDirectPanel) return tag;
+
+    const rawAttributes = tag.slice(4, -1);
+    const label = readAttribute(rawAttributes, "data-nb-tab-label");
+    if (!label) return tag;
+    const index = panelIndex++;
+    const panelId = readAttribute(rawAttributes, "id") ?? `${tabsId}-panel-${index}`;
+    tabs.push({
+      label,
+      icon: readAttribute(rawAttributes, "data-nb-tab-icon"),
+      panelId,
+    });
+
+    const additions = [
+      !/(?:^|\s)id=/.test(rawAttributes) && `id="${panelId}"`,
+      !/(?:^|\s)aria-labelledby=/.test(rawAttributes) && `aria-labelledby="${tabsId}-tab-${index}"`,
+      index > 0 && !/(?:^|\s)hidden(?:\s|=|$)/.test(rawAttributes) && "hidden",
+    ].filter(Boolean).join(" ");
+    return additions ? tag.slice(0, -1) + ` ${additions}>` : tag;
+  },
+);
+
+const triggerClass = "inline-flex shrink-0 cursor-pointer items-center gap-2 px-4 py-2 text-sm font-medium leading-6 whitespace-nowrap text-muted-foreground transition-colors hover:text-foreground aria-selected:text-primary focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-[-2px]";
+const isImageIcon = (icon: string) =>
+  icon.startsWith("/") ||
+  icon.startsWith("data:");
 ---
 
 <div
@@ -25,9 +89,40 @@ const { syncKey, class: className, ...attrs } = Astro.props;
   class={cn(className)}
   {...attrs}
 >
-  <TabsList />
+  <TabsList>
+    {tabs.map((tab, index) => (
+      <button
+        role="tab"
+        type="button"
+        id={`${tabsId}-tab-${index}`}
+        aria-controls={tab.panelId}
+        aria-selected={index === 0 ? "true" : "false"}
+        tabindex={index === 0 ? "0" : "-1"}
+        class={triggerClass}
+        data-nb-tabs-trigger
+      >
+        {tab.icon && (isImageIcon(tab.icon) ? (
+          <img
+            src={tab.icon}
+            alt=""
+            aria-hidden="true"
+            width="16"
+            height="16"
+            class="h-4 w-4 shrink-0 object-contain"
+          />
+        ) : (
+          <Icon
+            name={tab.icon === "aws" ? "fa6-brands:aws" : `fa6-solid:${tab.icon}`}
+            aria-hidden="true"
+            class="h-4 w-4 shrink-0"
+          />
+        ))}
+        {tab.label}
+      </button>
+    ))}
+  </TabsList>
   <div class="mt-3">
-    <slot />
+    <Fragment set:html={renderedContent} />
   </div>
 </div>
 
diff --git a/src/components/ui/tabs/tabs.client.ts b/src/components/ui/tabs/tabs.client.ts
index b80e2df0e..e93520eb2 100644
--- a/src/components/ui/tabs/tabs.client.ts
+++ b/src/components/ui/tabs/tabs.client.ts
@@ -4,14 +4,9 @@ import { mount, initTabs } from "@cloudflare/nimbus-docs/client";
 
 const TRIGGER_CLASS =
   "inline-flex shrink-0 cursor-pointer items-center gap-2 px-4 py-2 text-sm font-medium leading-6 whitespace-nowrap text-muted-foreground transition-colors hover:text-foreground aria-selected:text-primary focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-[-2px]";
-const MINTLIFY_ICON_CDN =
-  "https://d3gk2c5xim1je2.cloudfront.net/fontawesome/v7.2.0";
-
 function appendIcon(button: HTMLButtonElement, icon: string): void {
   const isImage =
     icon.startsWith("/") ||
-    icon.startsWith("http://") ||
-    icon.startsWith("https://") ||
     icon.startsWith("data:");
   if (isImage) {
     const image = document.createElement("img");
@@ -23,21 +18,9 @@ function appendIcon(button: HTMLButtonElement, icon: string): void {
     return;
   }
 
-  // Bare names are Mintlify Font Awesome icons, not relative image paths.
-  // Match Mintlify's masked-icon treatment so they inherit each tab's active
-  // or inactive text colour. AWS is the only branded tab icon in the source.
-  const family = icon === "aws" ? "brands" : "regular";
-  const url = `${MINTLIFY_ICON_CDN}/${family}/${encodeURIComponent(icon)}.svg`;
-  const mask = document.createElement("span");
-  mask.setAttribute("aria-hidden", "true");
-  mask.className = "block h-4 w-4 shrink-0";
-  mask.style.backgroundColor = "currentColor";
-  mask.style.setProperty(
-    "-webkit-mask",
-    `url("${url}") center / contain no-repeat`,
-  );
-  mask.style.mask = `url("${url}") center / contain no-repeat`;
-  button.append(mask);
+  // Named icons are normally rendered into the initial HTML. If a custom
+  // integration supplies panels only at runtime, keep its label usable
+  // without introducing a runtime dependency on an external icon service.
 }
 
 let counter = 0;
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 7483b9d37..2b85a7fb3 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -9,6 +9,7 @@ import { getCollectionLlmsUrl, getVersionStatus } from "@cloudflare/nimbus-docs"
 import AgentDirective from "@/components/AgentDirective.astro";
 import InkeepSearch from "@/components/InkeepSearch";
 import NimbusHead from "@/components/NimbusHead.astro";
+import { inlinePublicIcon } from "@/lib/build-icon";
 import type { BasePageProps } from "@cloudflare/nimbus-docs/types";
 
 export interface Alternate { hreflang: string; href: string }
@@ -51,6 +52,7 @@ const llmsIndexPath = collection
 const llmsUrl = Astro.site
   ? new URL(llmsIndexPath, Astro.site).href
   : llmsIndexPath;
+const projectLogo = inlinePublicIcon("/images/logo.svg");
 ---
 
 <!doctype html>
@@ -222,7 +224,7 @@ const llmsUrl = Astro.site
       data-website-id="5df6cc2b-732e-44e4-b789-aec81b70fe46"
       data-project-name="ClickHouse"
       data-project-color="#151515"
-      data-project-logo="https://avatars.githubusercontent.com/u/54801242?s=200&v=4"
+      data-project-logo={projectLogo}
       data-modal-disclaimer="This is a custom LLM for ClickHouse with access to all developer documentation, open GitHub Issues, YouTube videos, and resolved StackOverflow posts. Please note that answers are generated by AI and may not be fully accurate, so please use your best judgement."
       data-modal-example-questions="How to speed up queries?,How to use materialized views?"
       data-mcp-enabled="false"
diff --git a/src/lib/build-icon.ts b/src/lib/build-icon.ts
new file mode 100644
index 000000000..345dcc8e0
--- /dev/null
+++ b/src/lib/build-icon.ts
@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const publicRoot = path.resolve(fileURLToPath(new URL("../../.remote/public-build/", import.meta.url)));
+const cache = new Map<string, string>();
+const mimeTypes: Record<string, string> = {
+  ".avif": "image/avif",
+  ".gif": "image/gif",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+};
+
+/** Embed a checked-in public icon in the generated HTML as a data URL. */
+export function inlinePublicIcon(source: string): string {
+  if (source.startsWith("data:")) return source;
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    throw new Error(`External icon URLs are not supported: ${source}`);
+  }
+  if (!source.startsWith("/")) {
+    throw new Error(`Public icon paths must start with a slash: ${source}`);
+  }
+
+  const cached = cache.get(source);
+  if (cached) return cached;
+
+  const pathname = decodeURIComponent(source.split(/[?#]/, 1)[0] ?? source);
+  const filePath = path.resolve(publicRoot, `.${pathname}`);
+  if (!filePath.startsWith(publicRoot + path.sep)) {
+    throw new Error(`Icon path escapes the public directory: ${source}`);
+  }
+
+  const mimeType = mimeTypes[path.extname(filePath).toLowerCase()];
+  if (!mimeType) throw new Error(`Unsupported icon format: ${source}`);
+  const dataUrl = `data:${mimeType};base64,${fs.readFileSync(filePath).toString("base64")}`;
+  cache.set(source, dataUrl);
+  return dataUrl;
+}
diff --git a/src/lib/tab-id.ts b/src/lib/tab-id.ts
new file mode 100644
index 000000000..99ccbd330
--- /dev/null
+++ b/src/lib/tab-id.ts
@@ -0,0 +1,8 @@
+const requestCounters = new WeakMap<object, number>();
+
+/** Return a page-local stable ID for a server-rendered tab group. */
+export function nextTabId(locals: object): string {
+  const index = requestCounters.get(locals) ?? 0;
+  requestCounters.set(locals, index + 1);
+  return `nb-tabs-${index}`;
+}
diff --git a/src/styles/globals.css b/src/styles/globals.css
index 5f6533fd9..55d8cd768 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -2045,17 +2045,6 @@ body:not(:has([data-mobile-sidebar])) [data-menu-btn] {
 	object-fit: contain;
 }
 
-.ch-doc-card .ch-card-icon-mask {
-	color: #555800;
-	background: currentColor;
-	-webkit-mask: var(--ch-card-icon-mask) center / contain no-repeat;
-	mask: var(--ch-card-icon-mask) center / contain no-repeat;
-}
-
-[data-mode="dark"] .ch-doc-card .ch-card-icon-mask {
-	color: #fdff75;
-}
-
 .ch-doc-card h2 {
 	margin: 16px 0 0;
 	color: var(--nb-heading);

From 3060c6386b42294d2f4fca343a07d21d4bd5c31b Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 08:41:12 +0200
Subject: [PATCH 05/18] Fix build-time icons in remote previews

---
 bin/prepare-public.ts | 1 +
 src/lib/build-icon.ts | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/bin/prepare-public.ts b/bin/prepare-public.ts
index e8d590870..50d7bcaf5 100644
--- a/bin/prepare-public.ts
+++ b/bin/prepare-public.ts
@@ -111,6 +111,7 @@ fs.mkdirSync(output, { recursive: true });
 
 if (scope.remotePreview) {
   materialize(path.join(root, "public", "favicon.svg"), path.join(output, "favicon.svg"));
+  materialize(path.join(root, "images", "logo.svg"), path.join(output, "images", "logo.svg"));
   materialize(path.join(root, "images", "icons"), path.join(output, "images", "icons"));
 } else {
   for (const entry of fs.readdirSync(path.join(root, "public"))) {
diff --git a/src/lib/build-icon.ts b/src/lib/build-icon.ts
index 345dcc8e0..10b1dcd87 100644
--- a/src/lib/build-icon.ts
+++ b/src/lib/build-icon.ts
@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
-const publicRoot = path.resolve(fileURLToPath(new URL("../../.remote/public-build/", import.meta.url)));
+// Astro bundles this module into its prerender directory, so `import.meta.url`
+// no longer points back into `src` during a production build.
+const publicRoot = path.resolve(process.cwd(), ".remote/public-build");
 const cache = new Map<string, string>();
 const mimeTypes: Record<string, string> = {
   ".avif": "image/avif",

From c50f6ea7406140ab3f5eff92c1ed4140af56d405 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 08:54:00 +0200
Subject: [PATCH 06/18] Materialize public assets without symlinks

---
 bin/prepare-public.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/bin/prepare-public.ts b/bin/prepare-public.ts
index 50d7bcaf5..915794e74 100644
--- a/bin/prepare-public.ts
+++ b/bin/prepare-public.ts
@@ -115,8 +115,11 @@ if (scope.remotePreview) {
   materialize(path.join(root, "images", "icons"), path.join(output, "images", "icons"));
 } else {
   for (const entry of fs.readdirSync(path.join(root, "public"))) {
+    if (entry === "images" || entry === "img") continue;
     materialize(path.join(root, "public", entry), path.join(output, entry));
   }
+  materialize(path.join(root, "images"), path.join(output, "images"));
+  materialize(path.join(root, "img"), path.join(output, "img"));
 }
 
 for (const remote of manifest.remotes) {

From 7ae6912fada4665bb5675f140978d831d52b2dd1 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 09:03:00 +0200
Subject: [PATCH 07/18] Add Vercel Speed Insights

---
 package.json                 |  1 +
 pnpm-lock.yaml               | 33 +++++++++++++++++++++++++++++++++
 src/layouts/BaseLayout.astro |  2 ++
 3 files changed, 36 insertions(+)

diff --git a/package.json b/package.json
index e64a0b647..b8c1d74de 100644
--- a/package.json
+++ b/package.json
@@ -39,6 +39,7 @@
     "@readme/httpsnippet": "11.4.0",
     "@scalar/openapi-parser": "0.28.12",
     "@vercel/connect": "^2.0.2",
+    "@vercel/speed-insights": "^2.0.0",
     "astro": "~7.0.9",
     "clsx": "^2.1.1",
     "mermaid": "^11.17.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 193f4b98e..a7da057d9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -52,6 +52,9 @@ importers:
       '@vercel/connect':
         specifier: ^2.0.2
         version: 2.0.2
+      '@vercel/speed-insights':
+        specifier: ^2.0.0
+        version: 2.0.0(react@19.2.8)
       astro:
         specifier: ~7.0.9
         version: 7.0.9(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(rollup@4.63.1)(yaml@2.9.0)
@@ -2533,6 +2536,32 @@ packages:
     resolution: {integrity: sha512-RwXYtnt6za+5UO4IaLywN/6B95AlLqynPRUWRJxeJ/qufwkcLUbZNUxYtzT0uMpuraWhlNcGqPNGkTnZr4BGBw==}
     engines: {node: '>= 20'}
 
+  '@vercel/speed-insights@2.0.0':
+    resolution: {integrity: sha512-jwkNcrTeafWxjmWq4AHBaptSqZiJkYU5adLC9QBSqeim0GcqDMgN5Ievh8OG1rJ6W3A4l1oiP7qr9CWxGuzu3w==}
+    peerDependencies:
+      '@sveltejs/kit': ^1 || ^2
+      next: '>= 13'
+      nuxt: '>= 3'
+      react: ^18 || ^19 || ^19.0.0-rc
+      svelte: '>= 4'
+      vue: ^3
+      vue-router: ^4
+    peerDependenciesMeta:
+      '@sveltejs/kit':
+        optional: true
+      next:
+        optional: true
+      nuxt:
+        optional: true
+      react:
+        optional: true
+      svelte:
+        optional: true
+      vue:
+        optional: true
+      vue-router:
+        optional: true
+
   '@vitejs/plugin-react@5.2.0':
     resolution: {integrity: sha512-YmKkfhOAi3wsB1PhJq5Scj3GXMn3WvtQ/JC0xoopuHoXSdmtdStOpFrYaT1kie2YgFBcIe64ROzMYRjCrYOdYw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -7316,6 +7345,10 @@ snapshots:
       '@vercel/cli-exec': 1.0.1
       jose: 5.10.0
 
+  '@vercel/speed-insights@2.0.0(react@19.2.8)':
+    optionalDependencies:
+      react: 19.2.8
+
   '@vitejs/plugin-react@5.2.0(vite@7.3.6(@types/node@24.13.3)(jiti@2.7.0)(lightningcss@1.33.0)(yaml@2.9.0))':
     dependencies:
       '@babel/core': 7.29.7
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 2b85a7fb3..948188792 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -4,6 +4,7 @@ import "@fontsource-variable/jetbrains-mono";
 import "../styles/globals.css";
 import "../styles/prose.css";
 import { ClientRouter } from "astro:transitions";
+import SpeedInsights from "@vercel/speed-insights/astro";
 import { config } from "virtual:nimbus/config";
 import { getCollectionLlmsUrl, getVersionStatus } from "@cloudflare/nimbus-docs";
 import AgentDirective from "@/components/AgentDirective.astro";
@@ -241,5 +242,6 @@ const projectLogo = inlinePublicIcon("/images/logo.svg");
       codeCopy();
       headingAnchors();
     </script>
+    <SpeedInsights />
   </body>
 </html>

From 03beca70a41fe2cd568b85575475d27ab2a0df9c Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 09:38:02 +0200
Subject: [PATCH 08/18] Match Mintlify code block styling

Compared against https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/concepts/core-concepts/partitions
---
 .../components/RunnableCode/RunnableCode.jsx  | 20 ++---
 src/styles/globals.css                        | 86 ++++++++-----------
 src/styles/prose.css                          | 33 ++++++-
 3 files changed, 75 insertions(+), 64 deletions(-)

diff --git a/snippets/components/RunnableCode/RunnableCode.jsx b/snippets/components/RunnableCode/RunnableCode.jsx
index d4fc3aec6..0e2a5ae7b 100644
--- a/snippets/components/RunnableCode/RunnableCode.jsx
+++ b/snippets/components/RunnableCode/RunnableCode.jsx
@@ -35,7 +35,7 @@ export const RunnableCode = ({ children, run = false, showStats = true }) => {
 
   useEffect(() => {
     if (codeRef.current) {
-      const block = codeRef.current.querySelector('.code-block');
+      const block = codeRef.current.querySelector('.code-block, .nb-code-figure');
       if (block) {
         block.style.marginBottom = '0';
         block.style.marginTop = '0';
@@ -222,26 +222,16 @@ export const RunnableCode = ({ children, run = false, showStats = true }) => {
   };
 
   return (
-    <div className="not-prose" style={{ margin: '1rem 0', width: '100%', boxSizing: 'border-box', contain: 'inline-size' }}>
+    <div className="not-prose ch-runnable-code">
 
       {/* Code display + action bar */}
       <div>
-        <div ref={codeRef}>
+        <div ref={codeRef} className="ch-runnable-code__source">
           {children}
         </div>
 
         {/* Action bar */}
-        <div style={{
-          display: 'flex',
-          justifyContent: 'space-between',
-          alignItems: 'center',
-          padding: '6px 12px',
-          backgroundColor: headerBg,
-          borderWidth: '0 1px 1px 1px',
-          borderStyle: 'solid',
-          borderColor: isDark ? 'rgba(255,255,255,0.1)' : 'rgba(11,11,11,0.1)',
-          borderRadius: '0 0 4px 4px',
-        }}>
+        <div className="ch-runnable-code__actions">
           <div style={{ display: 'flex', alignItems: 'center', gap: '12px' }}>
             {results && (
               <button
@@ -409,4 +399,4 @@ export const RunnableCode = ({ children, run = false, showStats = true }) => {
       )}
     </div>
   );
-};
\ No newline at end of file
+};
diff --git a/src/styles/globals.css b/src/styles/globals.css
index 55d8cd768..824c8a9e6 100644
--- a/src/styles/globals.css
+++ b/src/styles/globals.css
@@ -405,15 +405,19 @@ body::-webkit-scrollbar {
 
 pre.astro-code {
 	position: relative;
-	margin: 1rem 0;
-	padding: 0.75rem 1rem;
-	border-radius: 0.5rem;
-	border: 1px solid var(--nb-border);
-	background-color: var(--nb-card);
+	margin: 1.25rem 0 2rem;
+	padding: 0.875rem 1rem;
+	border-radius: 0.25rem;
+	border: 1px solid color-mix(in srgb, var(--nb-foreground) 10%, transparent);
+	background-color: #fff;
 	overflow-x: auto;
-	font-family: var(--nb-font-mono);
-	font-size: 0.875rem;
-	line-height: 1.625;
+	font-family: "DejaVu Sans Mono", "Liberation Mono", MonoLisa, Consolas, monospace;
+	font-size: 0.8125rem;
+	line-height: 1.25;
+	font-variant-ligatures: none;
+}
+[data-mode="dark"] pre.astro-code {
+	background-color: #282828;
 }
 pre.astro-code > code {
 	background: transparent;
@@ -445,38 +449,40 @@ pre.astro-code .ch-sql-qid { color: #008b8b !important; }
 /* Copy button injected by initCodeCopy. */
 .nb-code-copy {
 	position: absolute;
-	top: 0.5rem;
-	right: 0.5rem;
+	top: 0.75rem;
+	right: 1rem;
 	display: inline-flex;
 	align-items: center;
 	justify-content: center;
-	width: 1.75rem;
-	height: 1.75rem;
+	width: 1.625rem;
+	height: 1.625rem;
 	margin: 0;
 	padding: 0;
-	border: 1px solid var(--nb-border);
+	border: 0;
 	border-radius: 0.375rem;
-	background: var(--nb-card);
-	color: var(--nb-muted-foreground);
+	background: transparent;
+	color: #9f9f9f;
 	cursor: pointer;
-	opacity: 0;
+	opacity: 1;
 	transition:
 		opacity 0.15s ease,
 		color 0.15s ease,
 		background 0.15s ease;
 	z-index: 2;
 }
-.nb-code-figure:hover .nb-code-copy,
-.nb-code-copy:focus-visible {
-	opacity: 1;
-}
 .nb-code-copy:hover {
 	color: var(--nb-foreground);
 	background: var(--nb-muted);
 }
 .nb-code-copy svg {
-	width: 0.875rem;
-	height: 0.875rem;
+	width: 1rem;
+	height: 1rem;
+}
+[data-mode="dark"] .nb-code-copy {
+	color: rgb(255 255 255 / 40%);
+}
+[data-mode="dark"] .nb-code-copy:hover {
+	color: rgb(255 255 255 / 60%);
 }
 .nb-code-copy[data-state="copied"] {
 	color: var(--nb-success);
@@ -490,12 +496,15 @@ pre.astro-code .ch-sql-qid { color: #008b8b !important; }
    children of overflow:auto containers. */
 .nb-code-figure {
 	position: relative;
-	margin: 1rem 0;
-	border: 1px solid var(--nb-border);
-	border-radius: 0.5rem;
-	background-color: var(--nb-card);
+	margin: 1.25rem 0 2rem;
+	border: 1px solid color-mix(in srgb, var(--nb-foreground) 10%, transparent);
+	border-radius: 0.25rem;
+	background-color: #fff;
 	overflow: hidden;
 }
+[data-mode="dark"] .nb-code-figure {
+	background-color: #282828;
+}
 .nb-code-figure > pre.astro-code {
 	margin: 0;
 	border: 0;
@@ -532,29 +541,10 @@ pre.astro-code .ch-sql-qid { color: #008b8b !important; }
 	text-transform: uppercase;
 }
 
-/* Language badge — pinned to the figure (which doesn't scroll), so it
-   stays at top-right even when the pre overflows horizontally. Hidden
-   when a figcaption is already showing the language (titled blocks). */
+/* Mintlify leaves the upper-right corner to the code actions rather than
+   repeating the fence language inside untitled blocks. */
 .nb-code-figure[data-nb-lang]:not(.nb-code-figure-titled)::before {
-	content: attr(data-nb-lang);
-	position: absolute;
-	top: 0.5rem;
-	right: 0.625rem;
-	padding: 0.0625rem 0.375rem;
-	border-radius: 0.25rem;
-	background: var(--nb-muted);
-	color: var(--nb-muted-foreground);
-	font-family: var(--nb-font-mono);
-	font-size: 0.6875rem;
-	letter-spacing: 0.02em;
-	text-transform: uppercase;
-	pointer-events: none;
-	opacity: 0.75;
-	transition: opacity 0.15s ease;
-	z-index: 1;
-}
-.nb-code-figure:hover::before {
-	opacity: 0;
+	display: none;
 }
 /* Hide plaintext/text "language" — it's noise. */
 .nb-code-figure[data-nb-lang="text"]::before,
diff --git a/src/styles/prose.css b/src/styles/prose.css
index c5e35004a..06b9b2002 100644
--- a/src/styles/prose.css
+++ b/src/styles/prose.css
@@ -288,7 +288,38 @@
    styling (background, border, padding) is reset because Shiki spans
    already carry their own colors via inline styles. */
 .docs-content .nb-code-figure {
-  margin: 1.5rem 0;
+  margin: 1.25rem 0 2rem;
+}
+
+/* Runnable snippets share the same code chrome, but the action bar is a
+   continuation of the block rather than a separate panel. */
+.docs-content .ch-runnable-code {
+  width: 100%;
+  margin: 1.25rem 0 2rem;
+  box-sizing: border-box;
+  contain: inline-size;
+}
+
+.docs-content .ch-runnable-code__source :is(.nb-code-figure, .code-block) {
+  margin: 0;
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.docs-content .ch-runnable-code__actions {
+  display: flex;
+  min-height: 2.625rem;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.375rem 0.75rem;
+  border: 1px solid color-mix(in srgb, var(--nb-foreground) 10%, transparent);
+  border-top: 0;
+  border-radius: 0 0 0.25rem 0.25rem;
+  background: color-mix(in srgb, var(--nb-foreground) 7%, var(--nb-background));
+}
+
+[data-mode="dark"] .docs-content .ch-runnable-code__actions {
+  background: #2a2a2a;
 }
 
 .docs-content pre.astro-code code {

From af15b3c1bfcfcf8b695132620728f80717437880 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 09:56:38 +0200
Subject: [PATCH 09/18] Match Mintlify AccordionGroup behavior

Compared against https://clickhouse.com/docs/get-started/use-cases/real-time-analytics and https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/get-started/use-cases/real-time-analytics.
---
 src/components/compat/AccordionGroup.astro    |  2 +-
 .../compat/accordion-group.client.ts          | 40 +++++++++++++++++++
 src/layouts/BaseLayout.astro                  |  1 +
 3 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 src/components/compat/accordion-group.client.ts

diff --git a/src/components/compat/AccordionGroup.astro b/src/components/compat/AccordionGroup.astro
index e438e20ef..5c7b63d74 100644
--- a/src/components/compat/AccordionGroup.astro
+++ b/src/components/compat/AccordionGroup.astro
@@ -2,4 +2,4 @@
 /** Mintlify `<AccordionGroup>`: visual grouping of accordions. */
 ---
 
-<div class="ch-accordion-group"><slot /></div>
+<div class="ch-accordion-group" data-ch-accordion-group><slot /></div>
diff --git a/src/components/compat/accordion-group.client.ts b/src/components/compat/accordion-group.client.ts
new file mode 100644
index 000000000..a256dcd7e
--- /dev/null
+++ b/src/components/compat/accordion-group.client.ts
@@ -0,0 +1,40 @@
+import { mount } from "@cloudflare/nimbus-docs/client";
+
+let groupSequence = 0;
+
+function initAccordionGroup(root: HTMLElement): () => void {
+  const accordions = Array.from(root.querySelectorAll<HTMLDetailsElement>("details.ch-accordion"))
+    .filter((accordion) => accordion.closest<HTMLElement>("[data-ch-accordion-group]") === root);
+
+  if (accordions.length < 2) return () => {};
+
+  const groupName = `ch-accordion-group-${++groupSequence}`;
+  accordions.forEach((accordion) => accordion.setAttribute("name", groupName));
+
+  // `name` gives modern browsers native exclusive disclosure behavior. Keep
+  // the toggle handler as a small compatibility layer for older engines.
+  const onToggle = (event: Event) => {
+    const opened = event.target;
+    if (!(opened instanceof HTMLDetailsElement) || !opened.open || !accordions.includes(opened)) return;
+
+    accordions.forEach((accordion) => {
+      if (accordion !== opened) accordion.open = false;
+    });
+  };
+
+  root.addEventListener("toggle", onToggle, true);
+
+  // Invalid authored state should still settle on a single expanded item.
+  accordions.filter((accordion) => accordion.open).slice(1).forEach((accordion) => {
+    accordion.open = false;
+  });
+
+  return () => {
+    root.removeEventListener("toggle", onToggle, true);
+    accordions.forEach((accordion) => {
+      if (accordion.getAttribute("name") === groupName) accordion.removeAttribute("name");
+    });
+  };
+}
+
+mount("[data-ch-accordion-group]", initAccordionGroup);
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 948188792..21a7f8cb3 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -238,6 +238,7 @@ const projectLogo = inlinePublicIcon("/images/logo.svg");
     <script src="../scripts/galaxy.ts"></script>
 
     <script>
+      import "../components/compat/accordion-group.client";
       import { codeCopy, headingAnchors } from "@cloudflare/nimbus-docs/client";
       codeCopy();
       headingAnchors();

From ef1769eb7219ff7d7c4a167e53b5615f5287d690 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 10:16:52 +0200
Subject: [PATCH 10/18] Preserve collapsed sidebar groups across navigation

Reproduced on https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/get-started/setup/self-managed/debian-ubuntu.
---
 src/components/ui/sidebar/SidebarGroup.astro |  7 ++++-
 src/components/ui/sidebar/sidebar.client.ts  | 28 +++++++++++++++++++-
 src/lib/sidebar-lazy.ts                      |  5 +++-
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/src/components/ui/sidebar/SidebarGroup.astro b/src/components/ui/sidebar/SidebarGroup.astro
index ecbc56a4d..05384987f 100644
--- a/src/components/ui/sidebar/SidebarGroup.astro
+++ b/src/components/ui/sidebar/SidebarGroup.astro
@@ -69,7 +69,11 @@ function hasActiveDescendant(items: SidebarItem[]): boolean {
 }
 
 const hasActive = Boolean(indexIsCurrent) || hasActiveDescendant(items);
-const isOpen = Boolean(section || hasActive || collapsed === false || collapsed === undefined);
+// Active routes must be visible even when their group is authored as
+// collapsed. Keep that temporary expansion separate from the state that the
+// persistence layer carries to the next route.
+const preferredOpen = Boolean(section || collapsed === false || collapsed === undefined);
+const isOpen = Boolean(hasActive || preferredOpen);
 // Collapsed groups off the active path ship a placeholder instead of their
 // subtree; sidebar-lazy.client.ts fetches the prebuilt fragment on expand.
 const lazy = !isOpen && Boolean(lazyKey) && items.length >= LAZY_MIN_CHILDREN;
@@ -93,6 +97,7 @@ const iconName = icon && !icon.startsWith("/")
   class={cn("group/accordion", className)}
   open={isOpen}
   data-nb-sidebar-group
+  data-nb-sidebar-preferred-open={preferredOpen ? "true" : "false"}
   {...attrs}
 >
   {section ? (
diff --git a/src/components/ui/sidebar/sidebar.client.ts b/src/components/ui/sidebar/sidebar.client.ts
index c6c52167b..dbc8d75e2 100644
--- a/src/components/ui/sidebar/sidebar.client.ts
+++ b/src/components/ui/sidebar/sidebar.client.ts
@@ -157,14 +157,40 @@ function initPersistence(root: HTMLElement): (() => void) | null {
     root;
   const hash = root.dataset.nbSidebarHash ?? "";
 
+  function readPreviousOpenState(): Record<string, boolean> | null {
+    try {
+      const raw = sessionStorage.getItem(STORAGE_KEY);
+      if (!raw) return null;
+      const previous = JSON.parse(raw) as Partial<SidebarState>;
+      if (previous.hash !== hash || !previous.open || Array.isArray(previous.open)) return null;
+      return previous.open;
+    } catch {
+      return null;
+    }
+  }
+
   function readState(): SidebarState {
     const groups = root.querySelectorAll<HTMLElement>("[data-nb-sidebar-group]");
     const open: Record<string, boolean> = {};
+    const previousOpen = readPreviousOpenState();
     groups.forEach((group) => {
       const trigger = ownedTrigger(group);
+      const key = groupKey(group);
+      const containsActivePage = Boolean(group.querySelector("[aria-current='page']"));
       // Fixed section headings have no disclosure trigger and always remain
       // open. Recording them as open also repairs state written by older code.
-      open[groupKey(group)] = !trigger || trigger.getAttribute("data-nb-state") === "open";
+      // A group on the active route is forced open so the current page stays
+      // visible. Do not mistake that temporary expansion for user intent:
+      // preserve the previous preference, or the authored default on the
+      // first visit.
+      if (trigger && containsActivePage) {
+        const previousValue = previousOpen?.[key];
+        open[key] = typeof previousValue === "boolean"
+          ? previousValue
+          : group.dataset.nbSidebarPreferredOpen === "true";
+      } else {
+        open[key] = !trigger || trigger.getAttribute("data-nb-state") === "open";
+      }
     });
     return { hash, open, scroll: scrollHost.scrollTop };
   }
diff --git a/src/lib/sidebar-lazy.ts b/src/lib/sidebar-lazy.ts
index e22b2ec86..09ad08b72 100644
--- a/src/lib/sidebar-lazy.ts
+++ b/src/lib/sidebar-lazy.ts
@@ -148,7 +148,10 @@ export function buildRailFromConfig(items: ConfigItem[], currentPath: string, ke
         if (norm(n.href) === target) { (n as { isCurrent?: boolean }).isCurrent = true; any = true; }
       } else if (n.type === "group") {
         const hit = mark(n.children);
-        if (hit) { n.collapsed = false; any = true; }
+        // SidebarGroup opens active ancestors itself. Do not overwrite the
+        // authored collapsed value: persistence needs that original value to
+        // distinguish a temporary active-route expansion from user intent.
+        if (hit) any = true;
       }
     }
     return any;

From 258a4363ee9135a2ffcb52b793502216b4dad2c1 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 10:39:31 +0200
Subject: [PATCH 11/18] Preserve page icons in generated sidebars

Compared against https://clickhouse.com/docs/integrations/clickpipes/home and https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/integrations/clickpipes/home.
---
 bin/gen-sidebar.ts                              | 15 ++++++++++-----
 src/components/ui/sidebar/Sidebar.astro         |  5 +++--
 src/components/ui/sidebar/SidebarChildren.astro |  5 +++--
 src/components/ui/sidebar/SidebarLink.astro     | 17 ++++++++++++++++-
 src/lib/sidebar-lazy.ts                         |  6 +++---
 5 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/bin/gen-sidebar.ts b/bin/gen-sidebar.ts
index 2cf54cc1a..62166c662 100644
--- a/bin/gen-sidebar.ts
+++ b/bin/gen-sidebar.ts
@@ -63,8 +63,8 @@ const tabs = (lang.tabs ?? []) as Obj[];
 
 // ---------------------------------------------------------------- labels
 type NavBadge = { text: string; variant: "success" | "info" | "warning" | "danger" | "note" };
-const labelCache = new Map<string, { label: string; exists: boolean; badge?: NavBadge }>();
-function pageInfo(page: string): { label: string; exists: boolean; badge?: NavBadge } {
+const labelCache = new Map<string, { label: string; exists: boolean; badge?: NavBadge; icon?: string; hidden?: boolean }>();
+function pageInfo(page: string): { label: string; exists: boolean; badge?: NavBadge; icon?: string; hidden?: boolean } {
   const cached = labelCache.get(page);
   if (cached) return cached;
   // Locale nav references are `es/...`; strip the locale so files resolve.
@@ -80,6 +80,8 @@ function pageInfo(page: string): { label: string; exists: boolean; badge?: NavBa
   const file = localizedFile ?? englishFile;
   let label = rel.split("/").pop() ?? rel;
   let badge: NavBadge | undefined;
+  let icon: string | undefined;
+  let hidden = false;
   if (file) {
     const src = fs.readFileSync(file, "utf8");
     const m = src.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -88,6 +90,8 @@ function pageInfo(page: string): { label: string; exists: boolean; badge?: NavBa
         const fm = (parseYaml(m[1]) ?? {}) as Record<string, unknown>;
         const st = fm.sidebarTitle ?? fm.title;
         if (typeof st === "string" && st.trim()) label = st.trim();
+        if (typeof fm.icon === "string" && fm.icon.trim()) icon = fm.icon.trim();
+        hidden = fm.hidden === true;
         if (typeof fm.openapi === "string") {
           const method = fm.openapi.match(/\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\//i)?.[1]?.toLowerCase() as HttpMethod | undefined;
           if (method) badge = { text: method.toUpperCase(), variant: apiMethodVariant(method) };
@@ -97,7 +101,7 @@ function pageInfo(page: string): { label: string; exists: boolean; badge?: NavBa
       }
     }
   }
-  const info = { label, exists: Boolean(file), badge };
+  const info = { label, exists: Boolean(file), badge, icon, hidden };
   labelCache.set(page, info);
   return info;
 }
@@ -191,7 +195,7 @@ function noteOrder(groupPath: string, pages: string[]) {
 
 // ---------------------------------------------------------------- conversion
 type NimbusItem =
-  | { label: string; link: string; badge?: NavBadge }
+  | { label: string; link: string; badge?: NavBadge; icon?: string }
   | { label: string; items: NimbusItem[]; collapsed?: boolean; segment?: string; landing?: string; icon?: string };
 
 function convertPages(pages: Json[], groupPath: string): NimbusItem[] {
@@ -218,7 +222,8 @@ function convertPages(pages: Json[], groupPath: string): NimbusItem[] {
       const info = pageInfo(p);
       if (!info.exists) missing.push(`${groupPath}: ${p}`);
       seenPages.add(p);
-      out.push({ label: info.label, link: pageLink(p), badge: info.badge });
+      if (info.hidden) continue;
+      out.push({ label: info.label, link: pageLink(p), badge: info.badge, icon: info.icon });
       continue;
     }
     if (p && typeof p === "object") {
diff --git a/src/components/ui/sidebar/Sidebar.astro b/src/components/ui/sidebar/Sidebar.astro
index aa6cbe129..e8e2810f0 100644
--- a/src/components/ui/sidebar/Sidebar.astro
+++ b/src/components/ui/sidebar/Sidebar.astro
@@ -20,6 +20,7 @@ interface Props extends HTMLAttributes<"div"> {
 const { items, persist = false, class: className, ...attrs } = Astro.props;
 const hash = sidebarHash(items);
 type LazyGroup = Extract<SidebarItem, { type: "group" }> & { _lazyKey?: string };
+type IconItem = { icon?: string };
 ---
 
 <div
@@ -48,11 +49,11 @@ type LazyGroup = Extract<SidebarItem, { type: "group" }> & { _lazyKey?: string }
         </li>
       ) : item.type === "external" ? (
         <li>
-          <SidebarLink label={item.label} href={item.href} badge={item.badge} target="_blank" rel="noopener" />
+          <SidebarLink label={item.label} href={item.href} badge={item.badge} icon={(item as IconItem).icon} target="_blank" rel="noopener" />
         </li>
       ) : (
         <li>
-          <SidebarLink label={item.label} href={item.href} isCurrent={item.isCurrent} badge={item.badge} />
+          <SidebarLink label={item.label} href={item.href} isCurrent={item.isCurrent} badge={item.badge} icon={(item as IconItem).icon} />
         </li>
       ),
     )}
diff --git a/src/components/ui/sidebar/SidebarChildren.astro b/src/components/ui/sidebar/SidebarChildren.astro
index 6612c2a95..399e4b27c 100644
--- a/src/components/ui/sidebar/SidebarChildren.astro
+++ b/src/components/ui/sidebar/SidebarChildren.astro
@@ -13,6 +13,7 @@ interface Props {
 
 const { items } = Astro.props;
 type LazyGroup = Extract<SidebarItem, { type: "group" }> & { _lazyKey?: string };
+type IconItem = { icon?: string };
 ---
 
 <ul class="mt-0.5 ml-3 list-none border-l border-border p-0 pl-2 flex flex-col gap-px" data-nb-sidebar-children>
@@ -31,9 +32,9 @@ type LazyGroup = Extract<SidebarItem, { type: "group" }> & { _lazyKey?: string }
           lazyKey={(item as LazyGroup)._lazyKey}
         />
       ) : item.type === "external" ? (
-        <SidebarLink label={item.label} href={item.href} badge={item.badge} target="_blank" rel="noopener" />
+        <SidebarLink label={item.label} href={item.href} badge={item.badge} icon={(item as IconItem).icon} target="_blank" rel="noopener" />
       ) : (
-        <SidebarLink label={item.label} href={item.href} isCurrent={item.isCurrent} badge={item.badge} />
+        <SidebarLink label={item.label} href={item.href} isCurrent={item.isCurrent} badge={item.badge} icon={(item as IconItem).icon} />
       )}
     </li>
   ))}
diff --git a/src/components/ui/sidebar/SidebarLink.astro b/src/components/ui/sidebar/SidebarLink.astro
index 082efab00..c43d08002 100644
--- a/src/components/ui/sidebar/SidebarLink.astro
+++ b/src/components/ui/sidebar/SidebarLink.astro
@@ -1,7 +1,9 @@
 ---
 import { cn } from "@/lib/cn";
+import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";
 import type { HTMLAttributes } from "astro/types";
 import { Badge } from "@/components/ui/badge";
+import { withBase } from "@/lib/base";
 import type { SidebarBadge } from "@cloudflare/nimbus-docs/types";
 
 interface Props extends HTMLAttributes<"a"> {
@@ -9,10 +11,18 @@ interface Props extends HTMLAttributes<"a"> {
   href: string;
   isCurrent?: boolean;
   badge?: SidebarBadge;
+  icon?: string;
 }
 
-const { label, href, isCurrent, badge, class: className, ...attrs } = Astro.props;
+const { label, href, isCurrent, badge, icon, class: className, ...attrs } = Astro.props;
 const isMethodBadge = typeof badge === "object" && /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/.test(badge.text);
+const iconName = icon && !icon.startsWith("/")
+  ? icon.includes(":")
+    ? icon
+    : icon === "aws"
+      ? "fa6-brands:aws"
+      : `fa6-solid:${icon}`
+  : undefined;
 ---
 
 <a
@@ -22,6 +32,11 @@ const isMethodBadge = typeof badge === "object" && /^(GET|POST|PUT|PATCH|DELETE|
   class={cn("nb-sidebar-link", className)}
   {...attrs}
 >
+  {icon && (icon.startsWith("/") ? (
+    <img src={withBase(icon)} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
+  ) : (
+    <Icon name={iconName!} class="shrink-0 h-4 w-4 text-muted-foreground" />
+  ))}
   {isMethodBadge && typeof badge === "object" && <Badge text={badge.text} variant={badge.variant} class="ch-sidebar-method" />}
   <span class="break-words">{label}</span>
   {badge && !isMethodBadge &&
diff --git a/src/lib/sidebar-lazy.ts b/src/lib/sidebar-lazy.ts
index 09ad08b72..e966b3ca0 100644
--- a/src/lib/sidebar-lazy.ts
+++ b/src/lib/sidebar-lazy.ts
@@ -17,7 +17,7 @@ export const LAZY_MIN_CHILDREN = 6;
 export const TAB_LABELS = new Set(["Home", "Database", "Solutions", "Integrations", "Resources"]);
 
 export type ConfigItem =
-  | { label: string; link: string; badge?: import("@cloudflare/nimbus-docs/types").SidebarBadge }
+  | { label: string; link: string; badge?: import("@cloudflare/nimbus-docs/types").SidebarBadge; icon?: string }
   | { label: string; items: ConfigItem[]; collapsed?: boolean; segment?: string; landing?: string; icon?: string };
 
 export function slugifyLabel(label: string): string {
@@ -79,8 +79,8 @@ export function toRendered(items: ConfigItem[], path: string[]): SidebarItem[] {
     }
     const href = /^(https?:)?\/\//.test(item.link) ? item.link : withBase(item.link);
     return /^(https?:)?\/\//.test(item.link)
-      ? ({ type: "external", label: item.label, href, order, badge: item.badge } as SidebarItem)
-      : ({ type: "link", label: item.label, href, order, badge: item.badge } as SidebarItem);
+      ? ({ type: "external", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem)
+      : ({ type: "link", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem);
   });
 }
 

From 736724b6ff0db173dc2c297e600b78c19f85aa6b Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 10:46:56 +0200
Subject: [PATCH 12/18] Inline sidebar image icons at build time

Verified on https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/integrations/clickpipes/home and compared with https://clickhouse.com/docs/integrations/clickpipes/home.
---
 src/components/ui/sidebar/SidebarGroup.astro | 8 +++++---
 src/components/ui/sidebar/SidebarLink.astro  | 5 +++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/components/ui/sidebar/SidebarGroup.astro b/src/components/ui/sidebar/SidebarGroup.astro
index 05384987f..47225fa01 100644
--- a/src/components/ui/sidebar/SidebarGroup.astro
+++ b/src/components/ui/sidebar/SidebarGroup.astro
@@ -21,6 +21,7 @@ import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@/component
 import SidebarChildren from "./SidebarChildren.astro";
 import { Badge } from "@/components/ui/badge";
 import { withBase } from "@/lib/base";
+import { inlinePublicIcon } from "@/lib/build-icon";
 import { LAZY_MIN_CHILDREN } from "@/lib/sidebar-lazy";
 import type { SidebarItem, SidebarBadge } from "@cloudflare/nimbus-docs/types";
 
@@ -91,6 +92,7 @@ const iconName = icon && !icon.startsWith("/")
       ? "ph:network"
       : `ph:${icon}`
   : undefined;
+const imageIcon = icon?.startsWith("/") ? inlinePublicIcon(icon) : undefined;
 ---
 
 <Collapsible
@@ -108,7 +110,7 @@ const iconName = icon && !icon.startsWith("/")
     >
       <span class="flex items-center gap-2 flex-1 min-w-0">
         {icon && (icon.startsWith("/") ? (
-          <img src={withBase(icon)} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
+          <img src={imageIcon} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
         ) : (
           <Icon name={iconName!} class="shrink-0 h-4 w-4 text-muted-foreground" />
         ))}
@@ -144,7 +146,7 @@ const iconName = icon && !icon.startsWith("/")
       >
         <span class="flex items-center gap-2 flex-1 min-w-0">
           {icon && (icon.startsWith("/") ? (
-            <img src={withBase(icon)} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
+            <img src={imageIcon} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
           ) : (
             <Icon name={iconName!} class="shrink-0 h-4 w-4 text-muted-foreground" />
           ))}
@@ -190,7 +192,7 @@ const iconName = icon && !icon.startsWith("/")
     >
       <span class="flex items-center gap-2 flex-1 min-w-0">
         {icon && (icon.startsWith("/") ? (
-          <img src={withBase(icon)} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
+          <img src={imageIcon} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
         ) : (
           <Icon name={iconName!} class="shrink-0 h-4 w-4 text-muted-foreground" />
         ))}
diff --git a/src/components/ui/sidebar/SidebarLink.astro b/src/components/ui/sidebar/SidebarLink.astro
index c43d08002..4ec35411e 100644
--- a/src/components/ui/sidebar/SidebarLink.astro
+++ b/src/components/ui/sidebar/SidebarLink.astro
@@ -3,7 +3,7 @@ import { cn } from "@/lib/cn";
 import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";
 import type { HTMLAttributes } from "astro/types";
 import { Badge } from "@/components/ui/badge";
-import { withBase } from "@/lib/base";
+import { inlinePublicIcon } from "@/lib/build-icon";
 import type { SidebarBadge } from "@cloudflare/nimbus-docs/types";
 
 interface Props extends HTMLAttributes<"a"> {
@@ -23,6 +23,7 @@ const iconName = icon && !icon.startsWith("/")
       ? "fa6-brands:aws"
       : `fa6-solid:${icon}`
   : undefined;
+const imageIcon = icon?.startsWith("/") ? inlinePublicIcon(icon) : undefined;
 ---
 
 <a
@@ -33,7 +34,7 @@ const iconName = icon && !icon.startsWith("/")
   {...attrs}
 >
   {icon && (icon.startsWith("/") ? (
-    <img src={withBase(icon)} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
+    <img src={imageIcon} alt="" aria-hidden="true" class="shrink-0 h-4 w-4" />
   ) : (
     <Icon name={iconName!} class="shrink-0 h-4 w-4 text-muted-foreground" />
   ))}

From 45d1f65d09685647647d338e69bf28d76d0f6d7a Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:10:01 +0200
Subject: [PATCH 13/18] Match the homepage MCP icon to page actions

Verified on https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/.
---
 bin/gen-homepage-react.ts                        | 14 ++++++++++++++
 src/components/ui/page-actions/PageActions.astro |  4 +++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/bin/gen-homepage-react.ts b/bin/gen-homepage-react.ts
index 0f7de0c7b..910be0f0c 100644
--- a/bin/gen-homepage-react.ts
+++ b/bin/gen-homepage-react.ts
@@ -9,10 +9,13 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { inlinePublicIcon } from "../src/lib/build-icon.ts";
 
 const root = process.cwd();
 const locales = ["en", "ar", "es", "fr", "ja", "ko", "pt-BR", "ru", "zh"];
 const outputDir = path.join(root, "src", "generated", "homepage");
+const mcpIcon = inlinePublicIcon("/images/icons/icon-mcp.svg");
+const mcpMask = /<span\s+aria-hidden="true"\s+className="shrink-0 w-\[15px\] h-\[15px\] bg-current ch-mcp-icon"\s+style=\{\{\s+WebkitMaskImage: `url\(\$\{assetBase\}\/images\/icons\/icon-mcp\.svg\)`,\s+maskImage: `url\(\$\{assetBase\}\/images\/icons\/icon-mcp\.svg\)`,\s+\}\}\s+\/>/g;
 
 function sourcePath(locale: string): string {
   return locale === "en" ? path.join(root, "index.mdx") : path.join(root, locale, "index.mdx");
@@ -56,7 +59,18 @@ function render(locale: string): string {
     .replaceAll(
       "typeof window !== 'undefined' && window.location.pathname.startsWith('/docs') ? '/docs' : ''",
       assetBaseExpression,
+    )
+    .replace(
+      mcpMask,
+      `<img src={${JSON.stringify(mcpIcon)}} alt="" aria-hidden="true" className="shrink-0 w-3.5 h-3.5 bg-transparent" />`,
+    )
+    .replace(
+      /(export const McpLink = \(\{ children \}\) => \{\r?\n)\s+const assetBase = [^\r\n]+;\r?\n/,
+      "$1",
     );
+  if (rewrittenDefinitions.includes("ch-mcp-icon")) {
+    throw new Error(`Could not replace the homepage MCP icon in ${file}`);
+  }
   return `// Generated from ${path.relative(root, file)}; do not edit.\n`
     + `import * as React from "react";\n`
     + `import { useEffect, useRef, useState } from "react";\n\n`
diff --git a/src/components/ui/page-actions/PageActions.astro b/src/components/ui/page-actions/PageActions.astro
index 8b42f4b68..3af5bde10 100644
--- a/src/components/ui/page-actions/PageActions.astro
+++ b/src/components/ui/page-actions/PageActions.astro
@@ -2,6 +2,7 @@
 import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";
 import { cn } from "@/lib/cn";
 import { withBase } from "@/lib/base";
+import { inlinePublicIcon } from "@/lib/build-icon";
 import type { HTMLAttributes } from "astro/types";
 
 interface Props extends HTMLAttributes<"div"> {
@@ -22,6 +23,7 @@ const issueUrl = new URL("https://github.com/ClickHouse/ClickHouse/issues/new");
 issueUrl.searchParams.set("template", "60_documentation-issue.yaml");
 issueUrl.searchParams.set("page", Astro.url.pathname);
 const documentationMcpHref = withBase("/resources/support-center/knowledge-base/setup-installation/set-up-clickhouse-documentation-mcp-server");
+const documentationMcpIcon = inlinePublicIcon("/images/icons/icon-mcp.svg");
 ---
 
 <div
@@ -87,7 +89,7 @@ const documentationMcpHref = withBase("/resources/support-center/knowledge-base/
 
     <a href={documentationMcpHref} class={baseBtn}>
       <img
-        src={withBase("/images/icons/icon-mcp.svg")}
+        src={documentationMcpIcon}
         alt=""
         aria-hidden="true"
         class="h-3.5 w-3.5 bg-transparent"

From 731bb3d8dfbb10eefe675594fd14bc2d66c361aa Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:10:18 +0200
Subject: [PATCH 14/18] Resolve checked-in icons from the source tree

Keep scoped remote previews independent of the reduced public asset output while preserving build-time icon embedding.
---
 src/lib/build-icon.ts | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/lib/build-icon.ts b/src/lib/build-icon.ts
index 10b1dcd87..96b9d257f 100644
--- a/src/lib/build-icon.ts
+++ b/src/lib/build-icon.ts
@@ -3,7 +3,8 @@ import path from "node:path";
 
 // Astro bundles this module into its prerender directory, so `import.meta.url`
 // no longer points back into `src` during a production build.
-const publicRoot = path.resolve(process.cwd(), ".remote/public-build");
+const projectRoot = process.cwd();
+const publicRoot = path.resolve(projectRoot, ".remote/public-build");
 const cache = new Map<string, string>();
 const mimeTypes: Record<string, string> = {
   ".avif": "image/avif",
@@ -29,8 +30,18 @@ export function inlinePublicIcon(source: string): string {
   if (cached) return cached;
 
   const pathname = decodeURIComponent(source.split(/[?#]/, 1)[0] ?? source);
-  const filePath = path.resolve(publicRoot, `.${pathname}`);
-  if (!filePath.startsWith(publicRoot + path.sep)) {
+  const sourceRoot = pathname.startsWith("/images/")
+    ? path.resolve(projectRoot, "images")
+    : pathname.startsWith("/img/")
+      ? path.resolve(projectRoot, "img")
+      : publicRoot;
+  const sourcePath = pathname.startsWith("/images/")
+    ? pathname.slice("/images".length)
+    : pathname.startsWith("/img/")
+      ? pathname.slice("/img".length)
+      : pathname;
+  const filePath = path.resolve(sourceRoot, `.${sourcePath}`);
+  if (!filePath.startsWith(sourceRoot + path.sep)) {
     throw new Error(`Icon path escapes the public directory: ${source}`);
   }
 

From 9cd9307e9f7793eb70ffd5c4874396e56bda07f6 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:10:37 +0200
Subject: [PATCH 15/18] Preserve sidebar context for hidden pages

Keep hidden routes in the generated navigation metadata for rail selection while omitting them from rendered navigation.
---
 bin/gen-sidebar.ts      |  5 ++---
 src/lib/sidebar-lazy.ts | 17 ++++++++++-------
 2 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/bin/gen-sidebar.ts b/bin/gen-sidebar.ts
index 62166c662..709d4356d 100644
--- a/bin/gen-sidebar.ts
+++ b/bin/gen-sidebar.ts
@@ -195,7 +195,7 @@ function noteOrder(groupPath: string, pages: string[]) {
 
 // ---------------------------------------------------------------- conversion
 type NimbusItem =
-  | { label: string; link: string; badge?: NavBadge; icon?: string }
+  | { label: string; link: string; badge?: NavBadge; icon?: string; hidden?: boolean }
   | { label: string; items: NimbusItem[]; collapsed?: boolean; segment?: string; landing?: string; icon?: string };
 
 function convertPages(pages: Json[], groupPath: string): NimbusItem[] {
@@ -222,8 +222,7 @@ function convertPages(pages: Json[], groupPath: string): NimbusItem[] {
       const info = pageInfo(p);
       if (!info.exists) missing.push(`${groupPath}: ${p}`);
       seenPages.add(p);
-      if (info.hidden) continue;
-      out.push({ label: info.label, link: pageLink(p), badge: info.badge, icon: info.icon });
+      out.push({ label: info.label, link: pageLink(p), badge: info.badge, icon: info.icon, hidden: info.hidden || undefined });
       continue;
     }
     if (p && typeof p === "object") {
diff --git a/src/lib/sidebar-lazy.ts b/src/lib/sidebar-lazy.ts
index e966b3ca0..affaffc33 100644
--- a/src/lib/sidebar-lazy.ts
+++ b/src/lib/sidebar-lazy.ts
@@ -17,7 +17,7 @@ export const LAZY_MIN_CHILDREN = 6;
 export const TAB_LABELS = new Set(["Home", "Database", "Solutions", "Integrations", "Resources"]);
 
 export type ConfigItem =
-  | { label: string; link: string; badge?: import("@cloudflare/nimbus-docs/types").SidebarBadge; icon?: string }
+  | { label: string; link: string; badge?: import("@cloudflare/nimbus-docs/types").SidebarBadge; icon?: string; hidden?: boolean }
   | { label: string; items: ConfigItem[]; collapsed?: boolean; segment?: string; landing?: string; icon?: string };
 
 export function slugifyLabel(label: string): string {
@@ -61,7 +61,7 @@ export function toRendered(items: ConfigItem[], path: string[]): SidebarItem[] {
   const groups = items.filter((i): i is Extract<ConfigItem, { items: ConfigItem[] }> => "items" in i);
   const keys = siblingKeys(groups.map((g) => g.label));
   let gi = 0;
-  return items.map((item, order) => {
+  return items.flatMap((item, order) => {
     if ("items" in item) {
       const key = [...path, keys[gi++]].join("/");
       const group = {
@@ -75,12 +75,15 @@ export function toRendered(items: ConfigItem[], path: string[]): SidebarItem[] {
         icon: item.icon,
       } as SidebarItem & { _lazyKey?: string };
       group._lazyKey = key;
-      return group;
+      return [group];
     }
+    if (item.hidden) return [];
     const href = /^(https?:)?\/\//.test(item.link) ? item.link : withBase(item.link);
-    return /^(https?:)?\/\//.test(item.link)
-      ? ({ type: "external", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem)
-      : ({ type: "link", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem);
+    return [
+      /^(https?:)?\/\//.test(item.link)
+        ? ({ type: "external", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem)
+        : ({ type: "link", label: item.label, href, order, badge: item.badge, icon: item.icon } as SidebarItem),
+    ];
   });
 }
 
@@ -167,7 +170,7 @@ export function sectionsFromConfig(items: ConfigItem[], currentPath: string): Ar
   const firstLink = (nodes: ConfigItem[]): string | undefined => {
     for (const n of nodes) {
       if ("items" in n) { const l = firstLink(n.items); if (l) return l; }
-      else if (!/^(https?:)?\/\//.test(n.link)) return n.link;
+      else if (!n.hidden && !/^(https?:)?\/\//.test(n.link)) return n.link;
     }
     return undefined;
   };

From 2159ad421e5150c31d4374d485df20e61d37e8da Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:25:35 +0200
Subject: [PATCH 16/18] Use canonical homepage paths for index pages

Observed on https://clickhouse-docs-bex5vtx0r-clickhouse.vercel.app/docs/.
---
 ar/index.mdx    | 3 ++-
 es/index.mdx    | 3 ++-
 fr/index.mdx    | 3 ++-
 index.mdx       | 3 ++-
 ja/index.mdx    | 3 ++-
 ko/index.mdx    | 3 ++-
 pt-BR/index.mdx | 3 ++-
 ru/index.mdx    | 3 ++-
 zh/index.mdx    | 3 ++-
 9 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/ar/index.mdx b/ar/index.mdx
index 87bacf92f..58dcc6a27 100644
--- a/ar/index.mdx
+++ b/ar/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/es/index.mdx b/es/index.mdx
index 5bb8698f2..66caf8fcc 100644
--- a/es/index.mdx
+++ b/es/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/fr/index.mdx b/fr/index.mdx
index b50ff8434..bb8f3ddbf 100644
--- a/fr/index.mdx
+++ b/fr/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/index.mdx b/index.mdx
index ac84b9236..2a88f500e 100644
--- a/index.mdx
+++ b/index.mdx
@@ -14,8 +14,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/ja/index.mdx b/ja/index.mdx
index b174f7f57..0b9378f07 100644
--- a/ja/index.mdx
+++ b/ja/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/ko/index.mdx b/ko/index.mdx
index 6ff6edc3e..9b03088eb 100644
--- a/ko/index.mdx
+++ b/ko/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/pt-BR/index.mdx b/pt-BR/index.mdx
index a4b0ac8d4..6c90ba552 100644
--- a/pt-BR/index.mdx
+++ b/pt-BR/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/ru/index.mdx b/ru/index.mdx
index 92809303f..6057594ff 100644
--- a/ru/index.mdx
+++ b/ru/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {
diff --git a/zh/index.mdx b/zh/index.mdx
index 2ef1dec86..92fe32d00 100644
--- a/zh/index.mdx
+++ b/zh/index.mdx
@@ -15,8 +15,9 @@ export const localizeHref = (href) => {
 
 export const withDocsBase = (href) => {
     if (!href || !href.startsWith('/')) return href;
+    const canonicalHref = href.replace(/\/index(?=[?#]|$)/, '');
     const base = typeof window === 'undefined' || window.location.pathname.startsWith('/docs') ? '/docs' : '';
-    return base + href;
+    return base + canonicalHref;
 };
 
 export const navigateTo = (event, href) => {

From 1743d0ced28df792baccdb6023faa443c68a5a9d Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 11:48:54 +0200
Subject: [PATCH 17/18] Persist manual active sidebar collapses

Reproduced on https://clickhouse-docs-co37ze1hn-clickhouse.vercel.app/docs/get-started/setup/self-managed/advanced.
---
 src/components/ui/sidebar/sidebar.client.ts | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/components/ui/sidebar/sidebar.client.ts b/src/components/ui/sidebar/sidebar.client.ts
index dbc8d75e2..dfe95579b 100644
--- a/src/components/ui/sidebar/sidebar.client.ts
+++ b/src/components/ui/sidebar/sidebar.client.ts
@@ -157,6 +157,18 @@ function initPersistence(root: HTMLElement): (() => void) | null {
     root;
   const hash = root.dataset.nbSidebarHash ?? "";
 
+  function handleDisclosureClick(event: MouseEvent): void {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const trigger = target.closest<HTMLElement>("[data-nb-collapsible-trigger]");
+    if (!trigger || !root.contains(trigger)) return;
+    const group = trigger.closest<HTMLElement>("[data-nb-sidebar-group]");
+    if (!group || group.hasAttribute("data-nb-opened-by-filter")) return;
+    group.setAttribute("data-nb-sidebar-user-toggled", "");
+  }
+
+  root.addEventListener("click", handleDisclosureClick);
+
   function readPreviousOpenState(): Record<string, boolean> | null {
     try {
       const raw = sessionStorage.getItem(STORAGE_KEY);
@@ -177,13 +189,15 @@ function initPersistence(root: HTMLElement): (() => void) | null {
       const trigger = ownedTrigger(group);
       const key = groupKey(group);
       const containsActivePage = Boolean(group.querySelector("[aria-current='page']"));
+      const userToggled = group.hasAttribute("data-nb-sidebar-user-toggled");
       // Fixed section headings have no disclosure trigger and always remain
       // open. Recording them as open also repairs state written by older code.
       // A group on the active route is forced open so the current page stays
       // visible. Do not mistake that temporary expansion for user intent:
       // preserve the previous preference, or the authored default on the
-      // first visit.
-      if (trigger && containsActivePage) {
+      // first visit. Once the user toggles it, the visible state is their new
+      // preference and must win over the automatic active-route expansion.
+      if (trigger && containsActivePage && !userToggled) {
         const previousValue = previousOpen?.[key];
         open[key] = typeof previousValue === "boolean"
           ? previousValue
@@ -226,6 +240,7 @@ function initPersistence(root: HTMLElement): (() => void) | null {
 
   return () => {
     observer.disconnect();
+    root.removeEventListener("click", handleDisclosureClick);
     document.removeEventListener("visibilitychange", handleVisibility);
     document.removeEventListener("astro:before-swap", save);
     window.removeEventListener("pagehide", save);

From e963418098833895f8f63d981eb48b00d85ab1c7 Mon Sep 17 00:00:00 2001
From: Shaun Struwig <41984034+Blargian@users.noreply.github.com>
Date: Wed, 9 Sep 2026 12:13:49 +0200
Subject: [PATCH 18/18] Preserve exact sidebar disclosure state

Reproduced on https://clickhouse-docs-co37ze1hn-clickhouse.vercel.app/docs/get-started/setup/self-managed/advanced.
---
 src/components/ui/sidebar/SidebarGroup.astro |  9 ++--
 src/components/ui/sidebar/sidebar.client.ts  | 43 +-------------------
 src/layouts/DocsLayout.astro                 |  7 ----
 src/lib/sidebar-lazy.ts                      |  5 +--
 4 files changed, 6 insertions(+), 58 deletions(-)

diff --git a/src/components/ui/sidebar/SidebarGroup.astro b/src/components/ui/sidebar/SidebarGroup.astro
index 47225fa01..6361395cf 100644
--- a/src/components/ui/sidebar/SidebarGroup.astro
+++ b/src/components/ui/sidebar/SidebarGroup.astro
@@ -70,11 +70,9 @@ function hasActiveDescendant(items: SidebarItem[]): boolean {
 }
 
 const hasActive = Boolean(indexIsCurrent) || hasActiveDescendant(items);
-// Active routes must be visible even when their group is authored as
-// collapsed. Keep that temporary expansion separate from the state that the
-// persistence layer carries to the next route.
-const preferredOpen = Boolean(section || collapsed === false || collapsed === undefined);
-const isOpen = Boolean(hasActive || preferredOpen);
+// This is the first-load state only. After hydration, route changes restore
+// the user's exact disclosure state without opening or closing active groups.
+const isOpen = Boolean(section || hasActive || collapsed === false || collapsed === undefined);
 // Collapsed groups off the active path ship a placeholder instead of their
 // subtree; sidebar-lazy.client.ts fetches the prebuilt fragment on expand.
 const lazy = !isOpen && Boolean(lazyKey) && items.length >= LAZY_MIN_CHILDREN;
@@ -99,7 +97,6 @@ const imageIcon = icon?.startsWith("/") ? inlinePublicIcon(icon) : undefined;
   class={cn("group/accordion", className)}
   open={isOpen}
   data-nb-sidebar-group
-  data-nb-sidebar-preferred-open={preferredOpen ? "true" : "false"}
   {...attrs}
 >
   {section ? (
diff --git a/src/components/ui/sidebar/sidebar.client.ts b/src/components/ui/sidebar/sidebar.client.ts
index dfe95579b..c6c52167b 100644
--- a/src/components/ui/sidebar/sidebar.client.ts
+++ b/src/components/ui/sidebar/sidebar.client.ts
@@ -157,54 +157,14 @@ function initPersistence(root: HTMLElement): (() => void) | null {
     root;
   const hash = root.dataset.nbSidebarHash ?? "";
 
-  function handleDisclosureClick(event: MouseEvent): void {
-    const target = event.target;
-    if (!(target instanceof Element)) return;
-    const trigger = target.closest<HTMLElement>("[data-nb-collapsible-trigger]");
-    if (!trigger || !root.contains(trigger)) return;
-    const group = trigger.closest<HTMLElement>("[data-nb-sidebar-group]");
-    if (!group || group.hasAttribute("data-nb-opened-by-filter")) return;
-    group.setAttribute("data-nb-sidebar-user-toggled", "");
-  }
-
-  root.addEventListener("click", handleDisclosureClick);
-
-  function readPreviousOpenState(): Record<string, boolean> | null {
-    try {
-      const raw = sessionStorage.getItem(STORAGE_KEY);
-      if (!raw) return null;
-      const previous = JSON.parse(raw) as Partial<SidebarState>;
-      if (previous.hash !== hash || !previous.open || Array.isArray(previous.open)) return null;
-      return previous.open;
-    } catch {
-      return null;
-    }
-  }
-
   function readState(): SidebarState {
     const groups = root.querySelectorAll<HTMLElement>("[data-nb-sidebar-group]");
     const open: Record<string, boolean> = {};
-    const previousOpen = readPreviousOpenState();
     groups.forEach((group) => {
       const trigger = ownedTrigger(group);
-      const key = groupKey(group);
-      const containsActivePage = Boolean(group.querySelector("[aria-current='page']"));
-      const userToggled = group.hasAttribute("data-nb-sidebar-user-toggled");
       // Fixed section headings have no disclosure trigger and always remain
       // open. Recording them as open also repairs state written by older code.
-      // A group on the active route is forced open so the current page stays
-      // visible. Do not mistake that temporary expansion for user intent:
-      // preserve the previous preference, or the authored default on the
-      // first visit. Once the user toggles it, the visible state is their new
-      // preference and must win over the automatic active-route expansion.
-      if (trigger && containsActivePage && !userToggled) {
-        const previousValue = previousOpen?.[key];
-        open[key] = typeof previousValue === "boolean"
-          ? previousValue
-          : group.dataset.nbSidebarPreferredOpen === "true";
-      } else {
-        open[key] = !trigger || trigger.getAttribute("data-nb-state") === "open";
-      }
+      open[groupKey(group)] = !trigger || trigger.getAttribute("data-nb-state") === "open";
     });
     return { hash, open, scroll: scrollHost.scrollTop };
   }
@@ -240,7 +200,6 @@ function initPersistence(root: HTMLElement): (() => void) | null {
 
   return () => {
     observer.disconnect();
-    root.removeEventListener("click", handleDisclosureClick);
     document.removeEventListener("visibilitychange", handleVisibility);
     document.removeEventListener("astro:before-swap", save);
     window.removeEventListener("pagehide", save);
diff --git a/src/layouts/DocsLayout.astro b/src/layouts/DocsLayout.astro
index 79255e5cf..fd03f3cb1 100644
--- a/src/layouts/DocsLayout.astro
+++ b/src/layouts/DocsLayout.astro
@@ -202,13 +202,6 @@ const pageBreadcrumb = breadcrumbs.length > 1 ? breadcrumbs.at(-2) : breadcrumbs
                 }
 
                 const active = scrollHost.querySelector("[aria-current='page']");
-                if (active) {
-                  let d = active.closest("[data-nb-sidebar-group]");
-                  while (d) {
-                    setGroupOpen(d, true);
-                    d = d.parentElement && d.parentElement.closest("[data-nb-sidebar-group]");
-                  }
-                }
 
                 const storedScroll = raw && state && typeof state.scroll === "number"
                   ? state.scroll
diff --git a/src/lib/sidebar-lazy.ts b/src/lib/sidebar-lazy.ts
index affaffc33..4e0abea7b 100644
--- a/src/lib/sidebar-lazy.ts
+++ b/src/lib/sidebar-lazy.ts
@@ -151,9 +151,8 @@ export function buildRailFromConfig(items: ConfigItem[], currentPath: string, ke
         if (norm(n.href) === target) { (n as { isCurrent?: boolean }).isCurrent = true; any = true; }
       } else if (n.type === "group") {
         const hit = mark(n.children);
-        // SidebarGroup opens active ancestors itself. Do not overwrite the
-        // authored collapsed value: persistence needs that original value to
-        // distinguish a temporary active-route expansion from user intent.
+        // SidebarGroup uses the active path for the initial server-rendered
+        // state. Do not overwrite the authored collapsed value here.
         if (hit) any = true;
       }
     }