@dogsbay/docs-layout 0.2.0-beta.0

package/src/DocsLayout.astro

@@ -0,0 +1,884 @@
+---
+/**
+ * Standard documentation page layout.
+ *
+ * Uses the same sidebar component system as the demo app:
+ * collapsible sidebar, dark mode toggle, frosted glass header,
+ * TOC sidebar, pagination footer.
+ *
+ * Usage:
+ *   <DocsLayout
+ *     siteName="My Docs"
+ *     title="Getting Started"
+ *     nav={navItems}
+ *     headings={headings}
+ *   >
+ *     <article>...</article>
+ *   </DocsLayout>
+ */
+import SidebarProvider from "@dogsbay/ui/sidebar/SidebarProvider.astro";
+import Sidebar from "@dogsbay/ui/sidebar/Sidebar.astro";
+import SidebarHeader from "@dogsbay/ui/sidebar/SidebarHeader.astro";
+import SidebarContent from "@dogsbay/ui/sidebar/SidebarContent.astro";
+import SidebarTrigger from "@dogsbay/ui/sidebar/SidebarTrigger.astro";
+import SidebarInset from "@dogsbay/ui/sidebar/SidebarInset.astro";
+import SidebarRail from "@dogsbay/ui/sidebar/SidebarRail.astro";
+import SidebarGroup from "@dogsbay/ui/sidebar/SidebarGroup.astro";
+import SidebarGroupLabel from "@dogsbay/ui/sidebar/SidebarGroupLabel.astro";
+import SidebarGroupContent from "@dogsbay/ui/sidebar/SidebarGroupContent.astro";
+import SidebarMenu from "@dogsbay/ui/sidebar/SidebarMenu.astro";
+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 Separator from "@dogsbay/ui/separator/Separator.astro";
+import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
+import DocsToc from "./DocsToc.astro";
+import DocsFooter from "./DocsFooter.astro";
+import SearchDialog from "./SearchDialog.astro";
+import TagList from "./TagList.astro";
+import StatusBadge from "./StatusBadge.astro";
+import TypeBadge from "./TypeBadge.astro";
+import PageActions from "./PageActions.astro";
+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 { resolveTagKeywords } from "./tag-list-data.js";
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+
+interface NavGroup {
+  label: string;
+  items: NavItem[];
+}
+
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface PaginationLink {
+  label: string;
+  href: string;
+}
+
+/**
+ * Closed palette of tag-chip colors. Mirrors `@dogsbay/types`'s
+ * `TagPaletteName`; restated here so this component stays
+ * standalone-importable. Keep in sync.
+ */
+type TagPaletteName =
+  | "blue"
+  | "amber"
+  | "emerald"
+  | "violet"
+  | "rose"
+  | "slate";
+
+interface Props {
+  /** Site name shown in header and sidebar logo */
+  siteName: string;
+  /** Page title for <title> tag */
+  title: string;
+  /** Home URL — also used as the base for the canonical link if absolute */
+  siteUrl?: string;
+  /** Navigation tree — flat array of items or grouped sections */
+  nav: NavItem[];
+  /** Optional grouped nav (label + items). If provided, renders sections with labels. */
+  navGroups?: NavGroup[];
+  /** Page headings for TOC */
+  headings?: Heading[];
+  /** Prev page link */
+  prev?: PaginationLink;
+  /** Next page link */
+  next?: PaginationLink;
+  /** GitHub/GitLab repo URL */
+  repoUrl?: string;
+  /** Edit URL for this page */
+  editUrl?: string;
+  /** Last updated date */
+  lastUpdated?: string;
+  /** Page description — also used as og:description / twitter:description */
+  description?: string;
+  /** Site-wide description used as fallback when page `description` is not set */
+  siteDescription?: string;
+  /** Copyright text (HTML allowed) */
+  copyright?: string;
+  /** Favicon path (default: "/favicon.ico"). Set to false to disable. */
+  favicon?: string | false;
+  /** Per-page OG image URL. Overrides defaultOgImage. */
+  ogImage?: string;
+  /** Site-level default OG image used when ogImage is not set */
+  defaultOgImage?: string;
+  /** OG content type. Default: "article" (use "website" for landing pages). */
+  ogType?: "article" | "website";
+  /** Canonical URL for this page. Auto-computed from siteUrl + pathname when absolute siteUrl is provided. */
+  canonicalUrl?: string;
+  /** Twitter / X handle including the leading "@" */
+  twitterHandle?: string;
+  /** Theme color hint for browsers (hex string) */
+  themeColor?: string;
+  /**
+   * Emit `<meta name="robots" content="noindex, nofollow">` 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.
+   */
+  noindex?: boolean;
+  /**
+   * Exclude this page from in-site Pagefind search results.
+   *
+   * Two-part wiring required because Pagefind resolves
+   * `data-pagefind-body` (declares the indexable region) BEFORE
+   * checking for ignore attributes elsewhere — the body-level
+   * ignore is dead code when a `data-pagefind-body` element
+   * exists deeper in the tree. So when this prop is set, the
+   * layout:
+   *
+   *  1. Adds `data-pagefind-ignore` to `<body>`.
+   *  2. **Omits** `data-pagefind-body` from `<main>`. Pagefind
+   *     falls back to body-scope, sees the ignore, skips the page.
+   *
+   * The auto-emitted taxonomy index / term routes pass this to
+   * keep navigation pages out of search-result clutter — a
+   * search for "auth" should return the actual auth tutorial,
+   * not the `/tags/concept/auth/` listing.
+   */
+  excludeFromSearch?: boolean;
+  /**
+   * Plausible analytics tracking domain. When set, a single deferred
+   * <script> tag is emitted in <head>. Cookie-less; no consent banner
+   * required for EU users.
+   */
+  plausibleDomain?: string;
+  /**
+   * Override Plausible script URL. Default:
+   * "https://plausible.io/js/script.js". Use for self-hosted or
+   * proxied installations.
+   */
+  plausibleScriptUrl?: string;
+  /**
+   * Disable the built-in Pagefind search dialog. Default: false.
+   * Set to true on sites that don't generate a Pagefind index.
+   */
+  hideSearch?: boolean;
+  /**
+   * Pagefind index path. Default: "/pagefind/". Override for sites with
+   * a non-root base path (e.g. "/docs/pagefind/").
+   */
+  pagefindUrl?: string;
+  /**
+   * Whether the site emits per-page `.md` mirror endpoints. When true,
+   * the page advertises `<link rel="alternate" type="text/markdown">`
+   * pointing at the mirror — agents that respect link relations can
+   * fetch the markdown variant without content negotiation.
+   */
+  mdMirror?: boolean;
+  /**
+   * Page tags from `meta.tags`. Renders a TagList chip strip below the
+   * page title when non-empty. Slash-nested values link into the
+   * matching taxonomy term page (e.g. `api/rest` → `/tags/api/rest/`).
+   */
+  tags?: string[];
+  /**
+   * Path prefix for tag term pages. Default `/tags`. Match the
+   * `taxonomies.tags.indexPath` declared in `dogsbay.config.yml`.
+   */
+  tagsIndexPath?: string;
+  /**
+   * Per-prefix display config for tag chips, sourced from
+   * `taxonomies.tags.prefixes` in `dogsbay.config.yml`. Keyed by
+   * the top-level segment of slash-nested tags (`concept`,
+   * `difficulty`, etc.). When set, `<TagList>` renders the tag as
+   * a two-part `<Label>: <Leaf>` chip in the prefix's palette
+   * color. Tags whose prefix has no entry render the flat single-
+   * color chip. See plans/tag-display-config.md.
+   */
+  tagPrefixes?: Record<string, { label?: string; color?: TagPaletteName }>;
+  /**
+   * Per-tag leaf-label overrides (slug → display string). URLs
+   * stay slug-based; only chip text changes. Sourced from
+   * `taxonomies.tags.labels`.
+   */
+  tagLabels?: Record<string, string>;
+  /**
+   * Page lifecycle status. Renders a StatusBadge for non-stable
+   * states. Drafts/deprecated get strong colors.
+   */
+  status?: "draft" | "preview" | "stable" | "deprecated";
+  /**
+   * Page type from `meta.type` (open string). Renders a TypeBadge.
+   * Diátaxis values get conventional colors; others use a neutral
+   * fallback.
+   *
+   * Also drives Schema.org `@type` selection for the auto-emitted
+   * JSON-LD: tutorials and how-tos render as `HowTo`, references
+   * as `TechArticle`, courses as `Course`. Pages without a
+   * recognised type fall back to `Article`.
+   */
+  pageType?: string;
+  /**
+   * Site- or page-specific structured data appended to the
+   * `<head>`. Each value is wrapped in its own
+   * `<script type="application/ld+json">` block alongside the
+   * auto-emitted Article / HowTo / etc. Lets writers layer in
+   * `Course`, `Person`, `Organization`, `BreadcrumbList`, etc.
+   * without forking the layout.
+   *
+   * When a page wants to **replace** the auto-emitted JSON-LD,
+   * pass `ogType: "website"` (suppresses the Article emit) and
+   * provide your own block via `customJsonLd`.
+   */
+  customJsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /**
+   * Audience facets from `meta.audience`. Surfaced as hidden
+   * `data-pagefind-filter="audience:<value>"` elements at the top
+   * of `<body>` so Pagefind picks them up during body indexing.
+   * Not rendered in the meta strip (would crowd the chip area);
+   * use a custom layout if you want them visible.
+   */
+  audience?: string[];
+  /**
+   * Category segments from `meta.category` (or auto-derived from
+   * path). Surfaced as hidden `data-pagefind-filter="category:<value>"`
+   * elements in `<body>`.
+   */
+  category?: string[];
+  /**
+   * Map of taxonomy name → index path for declared taxonomies.
+   * Used to wire links from built-in field badges (TypeBadge,
+   * StatusBadge) to their browse destination, when one exists.
+   * A field absent from this map renders as a plain badge with no
+   * link. Sourced from `taxonomies` declarations in
+   * `dogsbay.config.yml` and emitted to `site.json` by
+   * `format-astro`.
+   */
+  taxonomyIndexPaths?: Record<string, string>;
+  /**
+   * Per-taxonomy display config (`prefixes` + `labels`), keyed
+   * by taxonomy name. Forwarded to `<SearchDialog>` so facet
+   * checkboxes show human labels instead of slugs. Same data
+   * the chip components consume, just shaped per-taxonomy.
+   */
+  taxonomyDisplay?: Record<string, {
+    prefixes?: Record<string, { label?: string; color?: TagPaletteName }>;
+    labels?: Record<string, string>;
+  }>;
+  /**
+   * When `true`, render `<h1>{title}</h1>` at the top of `<main>`
+   * (above the meta strip) — used when the markdown body doesn't
+   * already start with a level-1 heading. format-astro computes
+   * this per page via `detectLeadingNodes`. Default `false` so
+   * existing consumers keep their current rendering until they
+   * opt in. See plans/auto-lede.md.
+   */
+  autoH1?: boolean;
+  /**
+   * When `true`, render `<p>{description}</p>` below the auto H1
+   * (or above the meta strip when there's no H1) — used when the
+   * markdown body doesn't already start with a leading paragraph.
+   * Reads `description` from props. Default `false`.
+   */
+  autoLede?: boolean;
+  /**
+   * Multi-source axis metadata for the current page. Stamped by
+   * the loader when ≥1 axis is active. Consumed by
+   * VersionSwitcher to compute the logical key
+   * (`<namespace>/<originalSlug>`) used to look up alternates
+   * in `switcherMap`.
+   *
+   * Undefined for pages outside the multi-source pipeline (root
+   * landing pages, custom pages added by hand).
+   */
+  multiSource?: {
+    namespace?: string;
+    version?: string;
+    locale?: string;
+    originalSlug: string;
+  };
+  /**
+   * Switcher data emitted by format-astro's `emitSwitcherMap`.
+   * The VersionSwitcher renders nothing when `versions.length <
+   * 2` (single-version site) or when the current page has no
+   * `multiSource.version`. Pass the raw JSON imported from
+   * `@/data/switcherMap.json`.
+   */
+  switcherMap?: {
+    versions: Array<{ id: string; label?: string; eol?: boolean; default?: boolean }>;
+    byLogicalKey: Record<string, Record<string, string>>;
+  };
+  /**
+   * URL prefix for the switcher's per-version landing fallback
+   * (`<basePath>/<version>/`). Defaults to "/docs".
+   */
+  basePath?: string;
+  /**
+   * Per-page LLM action UI. When set and `enabled !== false`, renders
+   * the PageActions cluster (Copy markdown + Open in Claude/ChatGPT/
+   * Perplexity/Gemini dropdown). See plans/llm-page-actions.md.
+   *
+   * `markdownBody` is the page's markdown source (for the Copy
+   * button). `mdUrl` is the absolute URL of the .md mirror endpoint.
+   * Both come from format-astro at emit time.
+   */
+  llmActions?: {
+    enabled?: boolean;
+    providers?: LlmProviderName[];
+    placement?: "header" | "inline" | "both";
+    copyButton?: boolean;
+    promptTemplate?: string;
+    footerLink?: boolean;
+    /** Markdown body to copy. */
+    markdownBody?: string;
+    /** Absolute or relative URL to the page's .md mirror. */
+    mdUrl?: string;
+  };
+  /**
+   * When `true`, drop the prose-width column cap (~48rem) and the
+   * right-hand TOC sidebar so the slot content can use the full
+   * width of the inset. Used by pages that already structure their
+   * own internal columns — OpenAPI endpoint pages composing
+   * `<ApiLayout>`, generated reference pages with side-by-side
+   * description + code panels, etc.
+   *
+   * format-astro sets this automatically when a page's tree is
+   * dominated by an `endpoint` TreeNode; manual consumers can opt
+   * in per-page.
+   */
+  wideLayout?: boolean;
+  class?: string;
+}
+
+const {
+  siteName,
+  title,
+  siteUrl = "/",
+  nav,
+  navGroups,
+  headings = [],
+  prev,
+  next,
+  repoUrl,
+  description,
+  siteDescription,
+  editUrl,
+  lastUpdated,
+  copyright,
+  favicon = "/favicon.ico",
+  ogImage,
+  defaultOgImage,
+  ogType = "article",
+  canonicalUrl,
+  twitterHandle,
+  themeColor,
+  noindex,
+  excludeFromSearch,
+  plausibleDomain,
+  plausibleScriptUrl,
+  hideSearch = false,
+  pagefindUrl = "/pagefind/",
+  mdMirror = false,
+  tags,
+  tagsIndexPath = "/tags",
+  tagPrefixes,
+  tagLabels,
+  status,
+  pageType,
+  audience,
+  category,
+  taxonomyIndexPaths,
+  taxonomyDisplay,
+  autoH1,
+  autoLede,
+  llmActions,
+  customJsonLd,
+  multiSource,
+  switcherMap,
+  basePath,
+  wideLayout = false,
+  class: className,
+} = Astro.props;
+
+// Resolve LLM action visibility + placement once. The component
+// guards against missing markdownBody / mdUrl internally, but we
+// also gate at the layout level so the slots stay empty when
+// disabled — keeps the markup lean for the common no-config case.
+const llmActionsEnabled =
+  !!llmActions
+  && llmActions.enabled !== false
+  && typeof llmActions.mdUrl === "string"
+  && llmActions.mdUrl.length > 0;
+const llmActionsPlacement = llmActions?.placement ?? "header";
+const showLlmActionsHeader =
+  llmActionsEnabled
+  && (llmActionsPlacement === "header" || llmActionsPlacement === "both");
+const showLlmActionsInline =
+  llmActionsEnabled
+  && (llmActionsPlacement === "inline" || llmActionsPlacement === "both");
+const llmFooterLink = !!llmActions && llmActions.footerLink !== false;
+
+// Compute href targets for the type / status badges. A field is
+// linkable only when (a) the user declared a `taxonomies.<field>`
+// block (so an indexPath flows through `taxonomyIndexPaths`) and
+// (b) the page has a value for it. Otherwise the badge stays
+// unlinked.
+const typeBadgeHref = (pageType && taxonomyIndexPaths?.type)
+  ? `${taxonomyIndexPaths.type.replace(/\/$/, "")}/${pageType}/`
+  : undefined;
+const statusBadgeHref = (status && status !== "stable" && taxonomyIndexPaths?.status)
+  ? `${taxonomyIndexPaths.status.replace(/\/$/, "")}/${status}/`
+  : undefined;
+
+const hasMetaStrip = (
+  (Array.isArray(tags) && tags.length > 0) ||
+  (status && status !== "stable") ||
+  (typeof pageType === "string" && pageType.length > 0)
+);
+
+const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
+
+// SEO computation
+const metaDescription = description ?? siteDescription;
+const metaOgImage = ogImage ?? defaultOgImage;
+const isAbsoluteSiteUrl = /^https?:\/\//.test(siteUrl);
+const computedCanonical = canonicalUrl
+  ?? (isAbsoluteSiteUrl
+    ? siteUrl.replace(/\/$/, "") + Astro.url.pathname
+    : undefined);
+
+// Markdown mirror — append `.md` to the current path for the alternate link
+const mdMirrorHref = mdMirror
+  ? (Astro.url.pathname.replace(/\/$/, "") || "") + ".md"
+  : undefined;
+
+// Tag keywords for HTML meta + JSON-LD. Slug-based identifiers
+// (`difficulty/1`, `concept/a11y`) mean nothing to a search-engine
+// indexer or social-card preview; the human label is the unit
+// machines should consume. The resolver applies `tagLabels`
+// overrides when set, falls back to the leaf segment otherwise.
+// Empty list when no tags — meta tags + JSON-LD silently elide.
+const tagKeywords = resolveTagKeywords(tags, tagLabels);
+
+// JSON-LD block. Shipped when ogType is "article" (the DocsLayout
+// default) and at least one keyword is set, so empty-frontmatter
+// pages don't ship a near-empty JSON blob. Schema.org's `keywords`
+// is a comma-separated string by convention.
+//
+// `@type` is selected from `pageType` (sourced from `meta.type`):
+// tutorial / how-to → HowTo; reference → TechArticle; course →
+// Course; everything else → Article. Matches the conventions
+// 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 } : {}),
+    }
+  : undefined;
+
+// `customJsonLd` accepts either a single object or an array.
+// Normalize to an array so we can iterate uniformly. Empty array
+// when not set so the template can `.map` safely.
+const customJsonLdBlocks = normalizeCustomJsonLd(customJsonLd);
+
+// Default icon for the site logo
+const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20"/></svg>';
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title} | {siteName}</title>
+
+    {metaDescription && <meta name="description" content={metaDescription} />}
+    {favicon !== false && <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" />}
+
+    {/* In-site Pagefind exclusion is wired via two coordinated
+       attributes on <body> and <main> below — see the prop docs
+       on `excludeFromSearch` for why both halves are needed. No
+       meta-tag signal here: <meta name="pagefind-exclude"> is
+       not in Pagefind's documented surface (the `data-pagefind-*`
+       attributes are), so emitting it would be cargo-culting. */}
+
+    {/* Pagefind facet filters live inside <main data-pagefind-body>
+       below — keeps them inside the indexed scope while excluding
+       sidebar / header / TOC text from per-page excerpts. See main. */}
+
+    {computedCanonical && <link rel="canonical" href={computedCanonical} />}
+    {mdMirrorHref && <link rel="alternate" type="text/markdown" href={mdMirrorHref} />}
+
+    {/* Open Graph */}
+    <meta property="og:type" content={ogType} />
+    <meta property="og:title" content={title} />
+    {metaDescription && <meta property="og:description" content={metaDescription} />}
+    <meta property="og:site_name" content={siteName} />
+    {computedCanonical && <meta property="og:url" content={computedCanonical} />}
+    {metaOgImage && <meta property="og:image" content={metaOgImage} />}
+    {/* OpenGraph article tags — one per resolved keyword. Used by
+       FB / LinkedIn / news aggregators to surface topic context.
+       Skipped when ogType is not "article" or no tags are set. */}
+    {ogType === "article" && tagKeywords.map((keyword) => (
+      <meta property="article:tag" content={keyword} />
+    ))}
+
+    {/* JSON-LD primary block — Article / HowTo / TechArticle /
+       Course depending on `pageType`. Emits keywords as a
+       Schema.org keywords string; Google reads this for topical
+       categorization in rich results. */}
+    {articleJsonLd && (
+      <script type="application/ld+json" set:html={JSON.stringify(articleJsonLd)} />
+    )}
+
+    {/* Per-page / per-site custom structured data. Layered on
+       top of the auto-emitted block so writers can describe
+       Course / Person / Organization / BreadcrumbList without
+       forking the layout. */}
+    {customJsonLdBlocks.map((block) => (
+      <script type="application/ld+json" set:html={JSON.stringify(block)} />
+    ))}
+
+    {/* Twitter / X */}
+    <meta name="twitter:card" content={metaOgImage ? "summary_large_image" : "summary"} />
+    <meta name="twitter:title" content={title} />
+    {metaDescription && <meta name="twitter:description" content={metaDescription} />}
+    {metaOgImage && <meta name="twitter:image" content={metaOgImage} />}
+    {twitterHandle && <meta name="twitter:site" content={twitterHandle} />}
+
+    {plausibleDomain && (
+      <script
+        is:inline
+        defer
+        data-domain={plausibleDomain}
+        src={plausibleScriptUrl ?? "https://plausible.io/js/script.js"}
+      ></script>
+    )}
+
+    <script is:inline>
+      if (localStorage.getItem("theme") === "dark") {
+        document.documentElement.classList.add("dark");
+      }
+    </script>
+    <slot name="head" />
+  </head>
+  <body
+    class="bg-background text-foreground antialiased"
+    data-pagefind-ignore={excludeFromSearch ? "" : undefined}
+  >
+    <SidebarProvider>
+      <Sidebar collapsible="icon">
+        <SidebarHeader>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton size="lg" href={siteUrl} isActive={currentPath === siteUrl || 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>
+                <div class="grid flex-1 text-left text-sm leading-tight">
+                  <span class="truncate font-semibold">{siteName}</span>
+                  <span class="truncate text-xs text-sidebar-foreground/70">Documentation</span>
+                </div>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarHeader>
+
+        <SidebarSeparator />
+
+        <SidebarContent>
+          {navGroups ? (
+            navGroups.map(group => (
+              <SidebarGroup>
+                <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
+                <SidebarGroupContent>
+                  <SidebarNavTree
+                    items={filterNavByAxis(group.items, {
+                      basePath: basePath ?? "/docs",
+                      version: multiSource?.version,
+                      locale: multiSource?.locale,
+                    })}
+                    currentPath={currentPath}
+                  />
+                </SidebarGroupContent>
+              </SidebarGroup>
+            ))
+          ) : (
+            <SidebarGroup>
+              <SidebarGroupContent>
+                <SidebarNavTree
+                  items={filterNavByAxis(nav, {
+                    basePath: basePath ?? "/docs",
+                    version: multiSource?.version,
+                    locale: multiSource?.locale,
+                  })}
+                  currentPath={currentPath}
+                />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          )}
+        </SidebarContent>
+
+        <SidebarRail />
+      </Sidebar>
+
+      <SidebarInset>
+        <header class="sticky top-0 z-40 flex h-12 shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
+          <SidebarTrigger class="-ml-1" />
+          <Separator orientation="vertical" class="mr-2 h-4" />
+          <span class="text-sm text-muted-foreground" data-page-title>{title}</span>
+          <div class="ml-auto flex items-center gap-2">
+            <slot name="header" />
+            {switcherMap && multiSource && (
+              <LocaleSwitcher
+                switcherMap={switcherMap}
+                multiSource={multiSource}
+                basePath={basePath ?? "/docs"}
+              />
+            )}
+            {switcherMap && multiSource && (
+              <VersionSwitcher
+                switcherMap={switcherMap}
+                multiSource={multiSource}
+                basePath={basePath ?? "/docs"}
+              />
+            )}
+            {showLlmActionsHeader && (
+              <PageActions
+                markdownBody={llmActions!.markdownBody}
+                mdUrl={llmActions!.mdUrl!}
+                providers={llmActions!.providers}
+                copyButton={llmActions!.copyButton}
+                promptTemplate={llmActions!.promptTemplate}
+              />
+            )}
+            {!hideSearch && (
+              <SearchDialog
+                pagefindUrl={pagefindUrl}
+                taxonomyDisplay={taxonomyDisplay}
+              />
+            )}
+            {repoUrl && (
+              <a href={repoUrl} target="_blank" rel="noopener" class="rounded-md p-2 text-muted-foreground hover:bg-accent hover:text-foreground" aria-label="Source repository">
+                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
+              </a>
+            )}
+            <ThemeToggle />
+          </div>
+        </header>
+
+        <div class:list={["flex min-w-0", className]}>
+          <main
+            class="min-w-0 flex-1 px-6 py-8 lg:px-12"
+            data-pagefind-body={excludeFromSearch ? undefined : ""}
+          >
+            {/*
+              Pagefind facet filter elements. Placed inside the
+              `data-pagefind-body` scope so Pagefind discovers
+              them while indexing. (When `excludeFromSearch` is
+              true the body element is omitted, but so is the
+              entire indexing of this page — these elements are
+              effectively dead too, which is correct for excluded
+              pages.) Moved here from the page-level <body>
+              after we discovered every page's excerpt was
+              just sidebar nav text (see DocsLayout history). The
+              data-pagefind-body attribute on <main> tells Pagefind
+              to ignore everything outside this element (sidebar,
+              header, TOC, footer), so per-page excerpts come from
+              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>
+            ))}
+            {Array.isArray(audience) && audience.map((value) => (
+              <div hidden data-pagefind-filter={`audience:${value}`}></div>
+            ))}
+            {Array.isArray(category) && category.map((value) => (
+              <div hidden data-pagefind-filter={`category:${value}`}></div>
+            ))}
+            {status && <div hidden data-pagefind-filter={`status:${status}`}></div>}
+            {pageType && <div hidden data-pagefind-filter={`type:${pageType}`}></div>}
+
+            <div class:list={["mx-auto", wideLayout ? "max-w-7xl" : "max-w-3xl"]}>
+              {/*
+                Inline page-actions cluster — sits below breadcrumb
+                / above auto-H1 so it reads as "actions for this
+                page" rather than "actions for the site". Header
+                placement is configured separately; both can be
+                active for sites that want sticky-header + inline.
+                See plans/llm-page-actions.md.
+              */}
+              {showLlmActionsInline && (
+                <div class="mb-4 flex justify-end" data-page-actions-inline>
+                  <PageActions
+                    markdownBody={llmActions!.markdownBody}
+                    mdUrl={llmActions!.mdUrl!}
+                    providers={llmActions!.providers}
+                    copyButton={llmActions!.copyButton}
+                    promptTemplate={llmActions!.promptTemplate}
+                  />
+                </div>
+              )}
+
+              {/*
+                Auto-rendered H1 + lede paragraph. format-astro
+                computes whether to inject these per page via
+                `detectLeadingNodes(page.tree)` — true when the
+                markdown body doesn't already provide them. Sites
+                with markdown-first authoring (`# Title\nLede.`)
+                see no change. See plans/auto-lede.md.
+
+                Order: H1 → lede → meta strip → page body. Reader
+                gets context (title, summary) before classification
+                (chips), then content.
+              */}
+              {autoH1 && (
+                <h1 class="text-3xl font-bold tracking-tight mb-2">
+                  {title}
+                </h1>
+              )}
+              {autoLede && description && (
+                <p class="text-lg text-muted-foreground mb-6">
+                  {description}
+                </p>
+              )}
+
+              {hasMetaStrip && (
+                <div
+                  class="not-prose mb-6 flex flex-wrap items-center gap-2"
+                  data-page-meta-strip
+                  data-pagefind-ignore
+                >
+                  {/*
+                    data-pagefind-ignore: chip text ("How-to",
+                    "Concept: Accessibility", etc.) is decorative —
+                    the same data lives in `data-pagefind-filter`
+                    elements above, structured for facets. Without
+                    this attribute, every page's search-result
+                    excerpt picked up "how to Concept:Accessibility"
+                    as its leading text, drowning out actual prose.
+                  */}
+                  {pageType && <TypeBadge type={pageType} href={typeBadgeHref} />}
+                  {status && <StatusBadge status={status} href={statusBadgeHref} />}
+                  {tags && tags.length > 0 && (
+                    <TagList
+                      tags={tags}
+                      indexPath={tagsIndexPath}
+                      prefixes={tagPrefixes}
+                      labels={tagLabels}
+                    />
+                  )}
+                </div>
+              )}
+
+              <slot />
+
+              <DocsFooter
+                editUrl={editUrl}
+                lastUpdated={lastUpdated}
+                prev={prev}
+                next={next}
+                copyright={copyright}
+                llmsLink={llmFooterLink}
+              />
+            </div>
+          </main>
+
+          {headings.length > 0 && !wideLayout && (
+            <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>
+          )}
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  </body>
+</html>
+
+<script>
+  import "@dogsbay/ui/sidebar/sidebar.ts";
+
+  function updateActiveNav() {
+    const path = window.location.pathname.replace(/\/$/, "") || "/";
+
+    document.querySelectorAll("[data-nav-href]").forEach((el) => {
+      const href = el.getAttribute("data-nav-href");
+      const isActive = href === path;
+      if (isActive) {
+        el.setAttribute("data-active", "");
+        el.classList.add("bg-sidebar-accent", "font-medium", "text-sidebar-accent-foreground");
+      } else {
+        el.removeAttribute("data-active");
+        el.classList.remove("bg-sidebar-accent", "font-medium", "text-sidebar-accent-foreground");
+      }
+    });
+
+    // Open ancestor details for active item
+    const activeLink = document.querySelector(`[data-nav-href="${path}"]`);
+    if (activeLink) {
+      let parent = activeLink.parentElement;
+      while (parent) {
+        if (parent.tagName === "DETAILS" && !parent.hasAttribute("open")) {
+          parent.setAttribute("open", "");
+        }
+        parent = parent.parentElement;
+      }
+    }
+
+    // Update page title in header
+    const titleEl = document.querySelector("[data-page-title]");
+    if (titleEl) {
+      titleEl.textContent = document.title.split(" | ")[0];
+    }
+  }
+
+  // Handle branch items with href — clicking label navigates, chevron toggles
+  function setupBranchLinks() {
+    document.querySelectorAll("summary[data-nav-href]").forEach((summary) => {
+      summary.addEventListener("click", (e) => {
+        const target = e.target as HTMLElement;
+        if (target.closest("[data-chevron]")) return;
+
+        const href = summary.getAttribute("data-nav-href");
+        if (!href) return;
+        const path = window.location.pathname.replace(/\/$/, "") || "/";
+        if (path === href) return;
+
+        e.preventDefault();
+        const details = summary.closest("details");
+        if (details) details.open = true;
+        window.location.href = href;
+      });
+    });
+  }
+
+  setupBranchLinks();
+  updateActiveNav();
+
+  document.addEventListener("astro:after-swap", () => {
+    setupBranchLinks();
+    updateActiveNav();
+  });
+</script>