@dogsbay/docs-layout 0.2.0-beta.9 → 0.2.0-beta.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.9",
+  "version": "0.2.0-beta.90",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,14 +29,14 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.9",
-    "@dogsbay/primitives": "0.2.0-beta.9"
+    "@dogsbay/ui": "0.2.0-beta.90",
+    "@dogsbay/primitives": "0.2.0-beta.90"
   },
   "devDependencies": {
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "astro": "^5.0.0 || ^6.0.0"
+    "astro": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "files": [
     "src",

package/src/DocsLayout.astro

@@ -31,9 +31,11 @@ import SidebarMenuItem from "@dogsbay/ui/sidebar/SidebarMenuItem.astro";
 import SidebarMenuButton from "@dogsbay/ui/sidebar/SidebarMenuButton.astro";
 import SidebarSeparator from "@dogsbay/ui/sidebar/SidebarSeparator.astro";
 import SidebarNavTree from "@dogsbay/ui/sidebar/SidebarNavTree.astro";
+import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
+import { resolveTocPlacement, hasDisplayableToc, type TocMode } from "./toc-placement.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -44,7 +46,7 @@ import VersionSwitcher from "./VersionSwitcher.astro";
 import LocaleSwitcher from "./LocaleSwitcher.astro";
 import { filterNavByAxis } from "./nav-filter.js";
 import type { LlmProviderName } from "./llm-actions.js";
-import { jsonLdTypeFor, normalizeCustomJsonLd } from "./json-ld.js";
+import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
 
 interface NavItem {
@@ -112,7 +114,13 @@ interface Props {
   siteDescription?: string;
   /** Copyright text (HTML allowed) */
   copyright?: string;
-  /** Favicon path (default: "/favicon.ico"). Set to false to disable. */
+  /**
+   * Favicon path. No host-root default — that 404s on subpath
+   * deploys. The format-astro emitter passes a combined-prefix
+   * path (e.g. `/<repo>/favicon.ico`) computed from site.url +
+   * basePath. Pass an empty string or `false` to disable. When
+   * undefined, no `<link rel="icon">` is emitted.
+   */
   favicon?: string | false;
   /** Per-page OG image URL. Overrides defaultOgImage. */
   ogImage?: string;
@@ -127,16 +135,25 @@ interface Props {
   /** Theme color hint for browsers (hex string) */
   themeColor?: string;
   /**
-   * Emit `<meta name="robots" content="noindex, nofollow">` when
+   * Emit `noindex` in the `<meta name="robots">` directive when
    * true. Tells external search engines (Google, Bing) to skip
-   * this page. Has NO effect on in-site Pagefind search — for
-   * that, use `excludeFromSearch`. The two are independent: a
-   * page can be excluded from external SEs but still appear in
-   * Pagefind (e.g. duplicate / old content readers might still
-   * want to find when they're already on the site), or vice
-   * versa.
+   * indexing this page. Independent of `nofollow` — common pattern
+   * for tag / index pages is noindex + follow (don't list this
+   * page in results, but do crawl through to the real content).
+   *
+   * Has NO effect on in-site Pagefind search — for that, use
+   * `excludeFromSearch`. The two are independent: a page can be
+   * excluded from external SEs but still appear in Pagefind (e.g.
+   * duplicate / old content readers might still want to find when
+   * they're already on the site), or vice versa.
    */
   noindex?: boolean;
+  /**
+   * Emit `nofollow` in the `<meta name="robots">` directive when
+   * true. Tells crawlers not to follow outbound links from this
+   * page. Independent of `noindex`. Default false.
+   */
+  nofollow?: boolean;
   /**
    * Exclude this page from in-site Pagefind search results.
    *
@@ -256,6 +273,23 @@ interface Props {
    * elements in `<body>`.
    */
   category?: string[];
+  /**
+   * Custom-taxonomy values from `meta.taxonomies` — anything declared
+   * in `taxonomies:` config that isn't one of the five hardcoded
+   * built-ins (`tags`, `category`, `audience`, `type`, `status`).
+   *
+   * Each entry becomes one `<div data-pagefind-filter="<name>:<value>">`
+   * inside the indexed body, so the search dialog grows a checkbox
+   * group for every custom taxonomy automatically. No extra config
+   * needed beyond declaring the taxonomy in `dogsbay.config.yml` —
+   * the search dialog discovers facets at index time and renders
+   * whatever Pagefind reports.
+   *
+   * Display labels for the checkboxes flow through
+   * `taxonomyDisplay[<name>]` (same prefix/label config that drives
+   * chip rendering elsewhere). When unset, raw slugs are shown.
+   */
+  taxonomies?: Record<string, string[]>;
   /**
    * Map of taxonomy name → index path for declared taxonomies.
    * Used to wire links from built-in field badges (TypeBadge,
@@ -324,6 +358,19 @@ interface Props {
    * (`<basePath>/<version>/`). Defaults to "/docs".
    */
   basePath?: string;
+  /**
+   * Sidebar navigation render mode.
+   *
+   * - `"client"` (default): emit the small `<DocsNavClient />` placeholder;
+   *   the tree is hydrated from `/_dogsbay/nav.json` once per session.
+   *   Page HTML shrinks dramatically at scale (~50 KB vs ~1.2 MB on a
+   *   2k-page site). No-JS users see a sitemap fallback link.
+   * - `"ssr-full"`: render the full nav tree into every page's HTML.
+   *   Best for very small sites or strict no-JS / SEO contexts.
+   *
+   * See plans/client-rendered-nav.md.
+   */
+  navMode?: "client" | "ssr-full";
   /**
    * Per-page LLM action UI. When set and `enabled !== false`, renders
    * the PageActions cluster (Copy markdown + Open in Claude/ChatGPT/
@@ -358,6 +405,17 @@ interface Props {
    * in per-page.
    */
   wideLayout?: boolean;
+  /**
+   * Table-of-contents placement. Default `"top"`.
+   * - `"top"` — expandable "On this page" disclosure at the top of the
+   *   article, identical on desktop and mobile; frees the right rail for the
+   *   `right-rail` named slot (e.g. an Ask AI panel).
+   * - `"popover"` — an "On this page" dropdown in the header.
+   * - `"rail"` — the classic right-hand TOC sidebar (pre-`toc` behaviour).
+   * - `"off"` — no table of contents.
+   * See plans/ask-branch1-placement-toc.md.
+   */
+  toc?: TocMode;
   class?: string;
 }
 
@@ -368,6 +426,7 @@ const {
   nav,
   navGroups,
   headings = [],
+  toc = "top",
   prev,
   next,
   repoUrl,
@@ -376,7 +435,7 @@ const {
   editUrl,
   lastUpdated,
   copyright,
-  favicon = "/favicon.ico",
+  favicon,
   ogImage,
   defaultOgImage,
   ogType = "article",
@@ -384,11 +443,18 @@ const {
   twitterHandle,
   themeColor,
   noindex,
+  nofollow,
   excludeFromSearch,
   plausibleDomain,
   plausibleScriptUrl,
   hideSearch = false,
-  pagefindUrl = "/pagefind/",
+  // No default for pagefindUrl — host-root absolute paths break on
+  // subpath-mounted deploys (GH Pages project pages, multi-mount
+  // Cloudflare). format-astro's emitter always passes the
+  // combined-prefix-aware URL; manual instantiation must too.
+  // Undefined here propagates to SearchDialog where the JS loader
+  // throws on first open instead of silently 404'ing the bundle.
+  pagefindUrl,
   mdMirror = false,
   tags,
   tagsIndexPath = "/tags",
@@ -398,6 +464,7 @@ const {
   pageType,
   audience,
   category,
+  taxonomies,
   taxonomyIndexPaths,
   taxonomyDisplay,
   autoH1,
@@ -407,6 +474,7 @@ const {
   multiSource,
   switcherMap,
   basePath,
+  navMode = "client",
   wideLayout = false,
   class: className,
 } = Astro.props;
@@ -428,6 +496,16 @@ const showLlmActionsInline =
   llmActionsEnabled
   && (llmActionsPlacement === "inline" || llmActionsPlacement === "both");
 const llmFooterLink = !!llmActions && llmActions.footerLink !== false;
+// Per-mount llms.txt URL — Dogsbay emits `<basePath>/llms.txt`
+// (sitemap-index pattern), so the footer link must be basePath-
+// prefixed too. Falls back to `/llms.txt` when basePath is empty
+// or unset, matching the platform's host-root single-site case.
+const llmsLinkHrefResolved = (() => {
+  const bp = (basePath ?? "").replace(/\/+$/, "");
+  if (!bp) return "/llms.txt";
+  const prefix = bp.startsWith("/") ? bp : `/${bp}`;
+  return `${prefix}/llms.txt`;
+})();
 
 // Compute href targets for the type / status badges. A field is
 // linkable only when (a) the user declared a `taxonomies.<field>`
@@ -447,15 +525,41 @@ const hasMetaStrip = (
   (typeof pageType === "string" && pageType.length > 0)
 );
 
+// TOC placement: which container(s) + the right-rail plugin region render.
+// Logic lives in toc-placement.ts so it's unit-tested; this file just consumes.
+const tocPlacement = resolveTocPlacement(toc, {
+  // Only show a TOC when the page has 2+ displayable headings (depth 2–3);
+  // the H1 doesn't count and a one-item TOC is noise. Keeps "On this page"
+  // off landing/welcome pages that are just an H1 + prose.
+  hasHeadings: hasDisplayableToc(headings),
+  wideLayout: !!wideLayout,
+});
+
 const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
 
 // SEO computation
 const metaDescription = description ?? siteDescription;
 const metaOgImage = ogImage ?? defaultOgImage;
 const isAbsoluteSiteUrl = /^https?:\/\//.test(siteUrl);
+// Compose canonical from ORIGIN + pathname. siteUrl may carry a
+// path component (the urlBase that drives Astro's `base` — see
+// plans/astro-base-from-site-url.md), and Astro.url.pathname
+// already includes that prefix. Naively concatenating siteUrl +
+// pathname double-counts the urlBase (e.g. .../repo/repo/page).
+// Strip path off siteUrl by reparsing as a URL.
+let canonicalOrigin: string | undefined;
+if (isAbsoluteSiteUrl) {
+  try {
+    const u = new URL(siteUrl);
+    canonicalOrigin = `${u.protocol}//${u.host}`;
+  } catch {
+    // Malformed siteUrl — fall back to the original (no path) behavior.
+    canonicalOrigin = siteUrl.replace(/\/$/, "");
+  }
+}
 const computedCanonical = canonicalUrl
-  ?? (isAbsoluteSiteUrl
-    ? siteUrl.replace(/\/$/, "") + Astro.url.pathname
+  ?? (canonicalOrigin
+    ? canonicalOrigin + Astro.url.pathname
     : undefined);
 
 // Markdown mirror — append `.md` to the current path for the alternate link
@@ -482,15 +586,16 @@ const tagKeywords = resolveTagKeywords(tags, tagLabels);
 // search engines key off for educational / tutorial / reference
 // SERP rendering. See `json-ld.ts` for the full mapping table.
 const articleJsonLd = (ogType === "article" && tagKeywords.length > 0)
-  ? {
-      "@context": "https://schema.org",
-      "@type": jsonLdTypeFor(pageType),
-      headline: title,
-      keywords: tagKeywords.join(", "),
-      ...(metaDescription ? { description: metaDescription } : {}),
-      ...(metaOgImage ? { image: metaOgImage } : {}),
-      ...(computedCanonical ? { url: computedCanonical } : {}),
-    }
+  ? buildArticleJsonLd({
+      type: jsonLdTypeFor(pageType),
+      title,
+      siteName,
+      keywords: tagKeywords,
+      description: metaDescription,
+      image: metaOgImage,
+      url: computedCanonical,
+      headings,
+    })
   : undefined;
 
 // `customJsonLd` accepts either a single object or an array.
@@ -510,11 +615,22 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     <title>{title} | {siteName}</title>
 
     {metaDescription && <meta name="description" content={metaDescription} />}
-    {favicon !== false && <link rel="icon" href={favicon} />}
+    {favicon && <link rel="icon" href={favicon} />}
     {themeColor && <meta name="theme-color" content={themeColor} />}
     {/* External search engine directive — orthogonal to in-site
-       Pagefind exclusion. */}
-    {noindex && <meta name="robots" content="noindex, nofollow" />}
+       Pagefind exclusion. `noindex` + `nofollow` are independent
+       bits per the meta-robots spec; emit only the directives that
+       are set. Combining them when both are set keeps the tag
+       compact (`<meta name="robots" content="noindex, nofollow">`)
+       instead of emitting two tags. */}
+    {(noindex || nofollow) && (
+      <meta
+        name="robots"
+        content={[noindex && "noindex", nofollow && "nofollow"]
+          .filter(Boolean)
+          .join(", ")}
+      />
+    )}
 
     {/* In-site Pagefind exclusion is wired via two coordinated
        attributes on <body> and <main> below — see the prop docs
@@ -529,6 +645,12 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
 
     {computedCanonical && <link rel="canonical" href={computedCanonical} />}
     {mdMirrorHref && <link rel="alternate" type="text/markdown" href={mdMirrorHref} />}
+    {/* Programmatic llms.txt discovery — agents that follow head
+       link rels get the per-mount llms.txt without parsing HTML.
+       Mirrors the existing _headers Link rel="describedby" used by
+       Cloudflare Pages / Workers. */}
+    <link rel="alternate" type="text/plain" title="llms.txt" href={llmsLinkHrefResolved} />
+    <link rel="describedby" type="text/plain" href={llmsLinkHrefResolved} />
 
     {/* Open Graph */}
     <meta property="og:type" content={ogType} />
@@ -592,7 +714,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarHeader>
           <SidebarMenu>
             <SidebarMenuItem>
-              <SidebarMenuButton size="lg" href={siteUrl} isActive={currentPath === siteUrl || currentPath === "/"}>
+              <SidebarMenuButton size="lg" href={basePath || "/"} isActive={currentPath === basePath || currentPath === "/"}>
                 <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
                   <Fragment set:html={siteIcon} />
                 </div>
@@ -608,7 +730,24 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarSeparator />
 
         <SidebarContent>
-          {navGroups ? (
+          {navMode === "client" ? (
+            // Client-render mode: emit one DocsNavClient placeholder
+            // inside a single SidebarGroup, regardless of navGroups.
+            // The group-label shape doesn't apply when the tree is
+            // hydrated by JS — multi-group nav is reconstructed
+            // client-side from the same /_dogsbay/nav.json shape.
+            // See plans/client-rendered-nav.md.
+            <SidebarGroup>
+              <SidebarGroupContent>
+                <DocsNavClient
+                  currentPath={currentPath}
+                  basePath={basePath ?? ""}
+                  version={multiSource?.version}
+                  locale={multiSource?.locale}
+                />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ) : navGroups ? (
             navGroups.map(group => (
               <SidebarGroup>
                 <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
@@ -650,6 +789,16 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
           <span class="text-sm text-muted-foreground" data-page-title>{title}</span>
           <div class="ml-auto flex items-center gap-2">
             <slot name="header" />
+            {tocPlacement.popoverToc && (
+              <details class="dba-toc-popover relative" data-toc-popover>
+                <summary class="cursor-pointer list-none rounded-md px-2 py-1.5 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
+                  On this page
+                </summary>
+                <div class="absolute right-0 z-50 mt-1 max-h-[70vh] w-64 overflow-y-auto rounded-md border bg-background p-3 shadow-md">
+                  <DocsToc headings={headings} title="" />
+                </div>
+              </details>
+            )}
             {switcherMap && multiSource && (
               <LocaleSwitcher
                 switcherMap={switcherMap}
@@ -676,6 +825,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             {!hideSearch && (
               <SearchDialog
                 pagefindUrl={pagefindUrl}
+                navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
               />
             )}
@@ -709,9 +859,30 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
               the actual page content. Filter elements live in here
               now to stay inside that scope.
             */}
-            {Array.isArray(tags) && tags.map((tag) => (
-              <div hidden data-pagefind-filter={`tag:${tag}`}></div>
-            ))}
+            {/*
+              Slash-nested tags whose prefix is declared in
+              `taxonomies.tags.prefixes` emit as per-prefix filter
+              divs so each prefix becomes its own Pagefind facet
+              column (Difficulty, Topic, Persona, …) instead of
+              pooling under a single "Tag" column.
+
+              Plain tags and tags whose prefix isn't declared fall
+              back to the pooled `tag:` filter — backward-compatible
+              for sites that haven't declared prefixes.
+
+              See plans/per-prefix-search-facets.md.
+            */}
+            {Array.isArray(tags) && tags.map((tag) => {
+              const slash = tag.indexOf("/");
+              if (slash > 0) {
+                const prefix = tag.slice(0, slash);
+                const leaf = tag.slice(slash + 1);
+                if (tagPrefixes && tagPrefixes[prefix]) {
+                  return <div hidden data-pagefind-filter={`${prefix}:${leaf}`}></div>;
+                }
+              }
+              return <div hidden data-pagefind-filter={`tag:${tag}`}></div>;
+            })}
             {Array.isArray(audience) && audience.map((value) => (
               <div hidden data-pagefind-filter={`audience:${value}`}></div>
             ))}
@@ -720,6 +891,20 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             ))}
             {status && <div hidden data-pagefind-filter={`status:${status}`}></div>}
             {pageType && <div hidden data-pagefind-filter={`type:${pageType}`}></div>}
+            {/*
+              Custom-taxonomy filters. Any taxonomy declared in
+              `dogsbay.config.yml` that isn't one of the five built-ins
+              flows through here, so `difficulty: intermediate` (etc.)
+              becomes a real Pagefind facet checkbox automatically.
+              See plans/beta-launch-followups.md for context.
+            */}
+            {taxonomies && Object.entries(taxonomies).flatMap(([name, values]) =>
+              Array.isArray(values)
+                ? values.map((value) => (
+                    <div hidden data-pagefind-filter={`${name}:${value}`}></div>
+                  ))
+                : []
+            )}
 
             <div class:list={["mx-auto", wideLayout ? "max-w-7xl" : "max-w-3xl"]}>
               {/*
@@ -793,6 +978,17 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 </div>
               )}
 
+              {tocPlacement.topToc && (
+                <details class="dba-toc-top not-prose mb-6 rounded-md border" data-toc-top>
+                  <summary class="cursor-pointer list-none px-3 py-2 text-sm font-medium text-muted-foreground">
+                    On this page
+                  </summary>
+                  <div class="border-t px-3 py-2">
+                    <DocsToc headings={headings} title="" />
+                  </div>
+                </details>
+              )}
+
               <slot />
 
               <DocsFooter
@@ -802,21 +998,46 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 next={next}
                 copyright={copyright}
                 llmsLink={llmFooterLink}
+                llmsLinkHref={llmsLinkHrefResolved}
               />
             </div>
           </main>
 
-          {headings.length > 0 && !wideLayout && (
+          {/* Classic right-hand TOC — only in `toc: rail` mode. */}
+          {tocPlacement.railToc && (
             <aside class="sticky top-12 hidden h-[calc(100vh-3rem)] w-56 shrink-0 overflow-y-auto border-l p-4 lg:block">
               <DocsToc headings={headings} />
             </aside>
           )}
+          {/* Right-rail plugin region — host for the `right-rail` named slot
+              (e.g. an Ask AI panel). Rendered in every non-rail mode and not
+              gated on headings, so a plugin can dock on heading-less pages.
+              Hidden when nothing fills it (see the empty-rail style below). */}
+          {tocPlacement.regionRail && (
+            <aside
+              class="dba-right-rail sticky top-12 hidden h-[calc(100vh-3rem)] w-80 shrink-0 overflow-y-auto border-l p-4 lg:block xl:w-96"
+              data-right-rail
+            >
+              <slot name="right-rail" />
+            </aside>
+          )}
         </div>
       </SidebarInset>
     </SidebarProvider>
   </body>
 </html>
 
+<style>
+  /* The right-rail plugin region renders unconditionally in non-rail TOC
+     modes so plugins (e.g. Ask AI) can dock into it. Until something fills
+     the `right-rail` slot it has no element children — hide it so an empty
+     bordered column doesn't show. (:has matches element children only; an
+     unfilled Astro named slot renders none.) */
+  aside[data-right-rail]:not(:has(*)) {
+    display: none;
+  }
+</style>
+
 <script>
   import "@dogsbay/ui/sidebar/sidebar.ts";
 

package/src/DocsNavClient.astro

@@ -0,0 +1,89 @@
+---
+/**
+ * Client-rendered drop-in replacement for SidebarNavTree.
+ *
+ * Emits an empty placeholder with the metadata the hydration script
+ * needs (nav-url to fetch, current-path to highlight, basePath for
+ * version/locale filtering). The actual tree DOM is rendered by
+ * `docs-nav-client.ts` after a single fetch of `nav.json` (cached
+ * once per session — subsequent navigations re-highlight without
+ * re-fetching, courtesy of view transitions).
+ *
+ * The placeholder shows a few skeleton rows so the layout doesn't
+ * shift when the real tree pops in. Skeleton uses the same width as
+ * the sidebar so visual jump is minimal even on a slow connection.
+ *
+ * Trade-offs vs SidebarNavTree:
+ *   - HTML per page: ~200 bytes (this placeholder + a tiny script
+ *     tag) vs ~600 KB+ for the SSR tree at scale.
+ *   - No-JS users see only the skeleton + the `<noscript>` fallback
+ *     link. A `sitemap.xml` link covers no-JS navigation.
+ *   - First paint waits for the JS bundle + the JSON fetch. On a 4G
+ *     connection that's typically <200 ms; the skeleton fills the
+ *     space until then.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+interface Props {
+  /** Current page's URL pathname; the script uses it to mark the active item. */
+  currentPath: string;
+  /**
+   * URL prefix the host serves under (combined `urlBase` + `basePath`).
+   * The script joins this with `/_dogsbay/nav.json` to locate the
+   * fetchable nav tree; also threaded to the version/locale filter
+   * so multi-axis sites work the same as SSR.
+   */
+  basePath?: string;
+  /** Current source's version axis value, if multi-version site. */
+  version?: string;
+  /** Current source's locale axis value, if multi-locale site. */
+  locale?: string;
+}
+
+const { currentPath, basePath = "", version, locale } = Astro.props;
+const navUrl = `${basePath}/_dogsbay/nav.json`;
+---
+
+<div
+  id="docs-nav-root"
+  data-nav-url={navUrl}
+  data-current-path={currentPath}
+  data-base-path={basePath}
+  data-version={version ?? ""}
+  data-locale={locale ?? ""}
+  aria-busy="true"
+  aria-label="Documentation navigation"
+>
+  <ul class="flex min-w-0 flex-col" data-sidebar="nav-tree" data-level="0">
+    {[0, 1, 2, 3, 4, 5].map((i) => (
+      <li>
+        <div
+          class="flex h-8 w-full items-center gap-2 rounded-md px-2"
+          aria-hidden="true"
+        >
+          <div class="h-2 w-2 rounded-full bg-sidebar-foreground/10" />
+          <div
+            class="h-2 rounded bg-sidebar-foreground/10"
+            style={`width: ${50 + ((i * 17) % 35)}%;`}
+          />
+        </div>
+      </li>
+    ))}
+  </ul>
+  <noscript>
+    <p class="px-2 py-1.5 text-sm text-sidebar-foreground/70">
+      JavaScript is required to render the sidebar. Use the
+      <a href={`${basePath}/sitemap.xml`} class="underline">sitemap</a>
+      to browse all pages.
+    </p>
+  </noscript>
+</div>
+
+<script>
+  // Single import — Astro/Vite bundles this into one shared chunk
+  // referenced from every page that uses DocsNavClient. Browsers
+  // cache the chunk, so the nav script ships once per session
+  // regardless of how many pages the user visits.
+  import { hydrateDocsNav } from "./docs-nav-client.ts";
+  hydrateDocsNav();
+</script>

package/src/DocsToc.astro

@@ -33,7 +33,7 @@ const filtered = headings.filter(h => h.depth >= minDepth && h.depth <= maxDepth
 
 {filtered.length > 0 && (
   <nav class:list={["text-sm", className]} aria-label="Table of contents">
-    <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>
+    {title && <div class="text-xs font-semibold uppercase text-muted-foreground">{title}</div>}
     <ul class="mt-2 space-y-1">
       {filtered.map(h => (
         <li>