@dogsbay/docs-layout 0.2.0-beta.93 → 0.2.0-beta.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.93",
+  "version": "0.2.0-beta.94",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
     "./TagList.astro": "./src/TagList.astro",
     "./StatusBadge.astro": "./src/StatusBadge.astro",
     "./TypeBadge.astro": "./src/TypeBadge.astro",
+    "./BlogIndex.astro": "./src/BlogIndex.astro",
     "./TaxonomyIndex.astro": "./src/TaxonomyIndex.astro",
     "./TaxonomyTerm.astro": "./src/TaxonomyTerm.astro",
     "./SearchDialog.astro": "./src/SearchDialog.astro",
@@ -29,12 +30,12 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.93",
-    "@dogsbay/primitives": "0.2.0-beta.93"
+    "@dogsbay/primitives": "0.2.0-beta.94",
+    "@dogsbay/ui": "0.2.0-beta.94"
   },
   "devDependencies": {
-    "happy-dom": "^20.8.9",
-    "vitest": "^3.0.0"
+    "happy-dom": "^20.10.6",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "astro": "^5.0.0 || ^6.0.0 || ^7.0.0"

package/src/BlogIndex.astro

@@ -0,0 +1,174 @@
+---
+/**
+ * BlogIndex — reverse-chronological list of posts.
+ *
+ * Reads the slice its route file hands it from `src/data/blog.json`
+ * (emitted by `format-astro/src/blog.ts` during `dogsbay site build`)
+ * and renders one card per post plus page navigation.
+ *
+ * All layout lives here rather than in the generated route files, so a
+ * design fix propagates on the next build instead of being baked into
+ * every emitted page — the same reason `TaxonomyIndex` exists.
+ *
+ * Uses the shared theme tokens only. The blog is the same site as the
+ * docs, so there is no blog palette, no blog typography scale, and no
+ * second set of card styles to keep in sync.
+ */
+interface BlogPostRef {
+  slug: string;
+  title: string;
+  url: string;
+  description?: string;
+  date?: string;
+  author?: string[];
+  tags?: string[];
+  heroImage?: string;
+  readingMinutes: number;
+}
+
+interface Props {
+  /** The posts for THIS page of the index, newest first. */
+  posts: BlogPostRef[];
+  /** URL-form index path, already basePath-prefixed. */
+  indexPath: string;
+  pageNo: number;
+  totalPages: number;
+  /** Page heading. Defaults to "Blog", or "Blog — page N" beyond page 1. */
+  heading?: string;
+}
+
+const {
+  posts,
+  indexPath,
+  pageNo,
+  totalPages,
+  heading = pageNo === 1 ? "Blog" : `Blog — page ${pageNo}`,
+} = Astro.props;
+
+/** Build time, so every reader sees the same string. See DocsLayout. */
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+const base = indexPath === "/" ? "" : indexPath.replace(/\/+$/, "");
+const hrefForPage = (n: number): string => (n === 1 ? `${base}/` : `${base}/page/${n}`);
+---
+
+{/*
+  The index needs its own <h1>. Post titles are <h2>, so without one the
+  page has an h2 with no h1 above it — a heading-order violation axe-core
+  flags, and a missing page heading for anyone navigating by headings.
+  The sticky header's site name is chrome, not a page heading.
+*/}
+<h1 class="text-3xl font-bold tracking-tight mb-8">{heading}</h1>
+
+{posts.length === 0 && (
+  <p class="text-muted-foreground">No posts yet.</p>
+)}
+
+<ul class="not-prose flex flex-col gap-8" data-blog-index>
+  {posts.map((post) => (
+    <li class="group">
+      <article class="flex flex-col gap-2">
+        {post.heroImage && (
+          <a href={post.url} tabindex="-1" aria-hidden="true">
+            {/*
+              aspect-boxed for the same reason as the post hero: an
+              unsized image in a list shifts every card below it.
+            */}
+            <img
+              src={post.heroImage}
+              alt=""
+              class="mb-2 w-full rounded-lg border border-border object-cover aspect-[2/1]"
+              loading="lazy"
+              decoding="async"
+            />
+          </a>
+        )}
+
+        <h2 class="text-xl font-semibold tracking-tight">
+          <a
+            href={post.url}
+            class="text-foreground no-underline hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+          >
+            {post.title}
+          </a>
+        </h2>
+
+        {/*
+          Byline mirrors the post page's, minus the reading estimate's
+          separator noise. data-pagefind-ignore because the same values
+          are indexed as structured filters on the post itself; without
+          it, every card's date leads its search excerpt.
+        */}
+        <div
+          class="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground"
+          data-pagefind-ignore
+        >
+          {post.author && post.author.length > 0 && (
+            <span class="font-medium text-foreground">{post.author.join(", ")}</span>
+          )}
+          {post.author && post.author.length > 0 && post.date && (
+            <span aria-hidden="true">&middot;</span>
+          )}
+          {post.date && <time datetime={post.date}>{formatDate(post.date)}</time>}
+          {/*
+            Guarded like the post page's byline. Unconditional, a post with
+            neither author nor date opened with a stray "· 5 min read", and
+            the card disagreed with the page it linked to.
+          */}
+          {(post.author?.length || post.date) && <span aria-hidden="true">&middot;</span>}
+          <span>{post.readingMinutes} min read</span>
+        </div>
+
+        {post.description && (
+          <p class="text-muted-foreground">{post.description}</p>
+        )}
+      </article>
+    </li>
+  ))}
+</ul>
+
+{totalPages > 1 && (
+  <nav class="not-prose mt-12 flex items-center justify-between" aria-label="Blog pages">
+    {pageNo > 1 ? (
+      <a
+        href={hrefForPage(pageNo - 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="prev"
+      >
+        &larr; Newer posts
+      </a>
+    ) : (
+      <span></span>
+    )}
+
+    <span class="text-sm text-muted-foreground">
+      Page {pageNo} of {totalPages}
+    </span>
+
+    {pageNo < totalPages ? (
+      <a
+        href={hrefForPage(pageNo + 1)}
+        class="text-sm text-foreground no-underline hover:underline"
+        rel="next"
+      >
+        Older posts &rarr;
+      </a>
+    ) : (
+      <span></span>
+    )}
+  </nav>
+)}

package/src/DocsFooter.astro

@@ -14,6 +14,14 @@ interface Props {
   lastUpdated?: string;
   prev?: PaginationLink;
   next?: PaginationLink;
+  /**
+   * Captions above the prev/next titles. Default "Previous" / "Next",
+   * which is right for docs, where adjacency is position in the sidebar.
+   * A blog's adjacency is TIME, so it passes "Newer" / "Older" — the
+   * link means something different there and the label should say so.
+   */
+  prevLabel?: string;
+  nextLabel?: string;
   copyright?: string;
   /**
    * When true, render a low-key footer link to `/llms.txt` so
@@ -32,6 +40,8 @@ const {
   lastUpdated,
   prev,
   next,
+  prevLabel = "Previous",
+  nextLabel = "Next",
   copyright,
   llmsLink = false,
   llmsLinkHref = "/llms.txt",
@@ -74,7 +84,7 @@ function formatDate(value: string): string {
         <a href={prev.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="prev">
           <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"><polyline points="15 18 9 12 15 6"/></svg>
           <div class="text-left">
-            <div class="text-xs text-muted-foreground">Previous</div>
+            <div class="text-xs text-muted-foreground">{prevLabel}</div>
             <div>{prev.label}</div>
           </div>
         </a>
@@ -82,7 +92,7 @@ function formatDate(value: string): string {
       {next ? (
         <a href={next.href} class="inline-flex items-center gap-2 rounded-md border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent" rel="next">
           <div class="text-right">
-            <div class="text-xs text-muted-foreground">Next</div>
+            <div class="text-xs text-muted-foreground">{nextLabel}</div>
             <div>{next.label}</div>
           </div>
           <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"><polyline points="9 18 15 12 9 6"/></svg>

package/src/DocsLayout.astro

@@ -36,6 +36,7 @@ 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 { linkIconAttrs } from "./link-icons.js";
 import DocsFooter from "./DocsFooter.astro";
 import SearchDialog from "./SearchDialog.astro";
 import TagList from "./TagList.astro";
@@ -405,6 +406,32 @@ interface Props {
    * in per-page.
    */
   wideLayout?: boolean;
+
+  /**
+   * Which chrome this page wears.
+   *
+   * `"docs"` (default) is the full documentation shell. `"blog"` drops
+   * the sidebar and its nav fetch, and turns on the byline row — the
+   * blog is the same SITE, not a second design system, so the header,
+   * footer, search, page actions, TOC and every theme token stay
+   * identical. See plans/blog-capability.md Phase 3.
+   */
+  chrome?: "docs" | "blog";
+
+  /** Post authors. No byline is rendered when absent — never a placeholder. */
+  author?: string[];
+  /** ISO publish date for the byline. */
+  publishedDate?: string;
+  /** ISO updated date; shown only when it differs from publishedDate. */
+  updatedDate?: string;
+  /**
+   * Reading estimate in whole minutes. Computed at EMIT time from the
+   * TreeNode word count — a browser-side count would re-walk the DOM on
+   * every load for a number that cannot change.
+   */
+  readingMinutes?: number;
+  /** Optional hero image URL, rendered above the prose. */
+  heroImage?: string;
   /**
    * Table-of-contents placement. Default `"top"`.
    * - `"top"` — expandable "On this page" disclosure at the top of the
@@ -416,6 +443,18 @@ interface Props {
    * See plans/ask-branch1-placement-toc.md.
    */
   toc?: TocMode;
+  /**
+   * Internal/external link-icon glyphs. When set, a small trailing icon
+   * marks links in the prose — external (absolute / protocol-relative
+   * href) vs internal (root / relative) — classified purely by href
+   * shape in CSS. Either side may be absent to mark only that link kind.
+   * Sourced from `content.linkIcons` in `dogsbay.config.yml`.
+   * See plans/link-resolution-and-icons.md.
+   */
+  linkIcons?: {
+    external?: string;
+    internal?: string;
+  };
   class?: string;
 }
 
@@ -476,9 +515,22 @@ const {
   basePath,
   navMode = "client",
   wideLayout = false,
+  chrome = "docs",
+  author,
+  publishedDate,
+  updatedDate,
+  readingMinutes,
+  heroImage,
+  linkIcons,
   class: className,
 } = Astro.props;
 
+// Link icons — classified in CSS by href shape. `data-link-icons`
+// lists which kinds are active; the glyphs ride in CSS custom props
+// (single-quoted so they're valid `content:` string values).
+const { tokens: _linkIconTokens, style: _linkIconStyle } =
+  linkIconAttrs(linkIcons);
+
 // 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
@@ -562,9 +614,54 @@ const computedCanonical = canonicalUrl
     ? canonicalOrigin + Astro.url.pathname
     : undefined);
 
-// Markdown mirror — append `.md` to the current path for the alternate link
+/**
+ * Format an ISO date for a byline.
+ *
+ * Runs at BUILD time, so the output is baked into the HTML and every
+ * reader sees the same string — no hydration flash, and no dependence on
+ * the visitor's locale for a date the author wrote. Falls back to the
+ * raw value if it will not parse, so a typo shows up as itself rather
+ * than as "Invalid Date".
+ */
+function _formatPostDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  // timeZone: "UTC" is load-bearing. parseMeta normalizes `created:
+  // 2026-01-01` to "2026-01-01T00:00:00.000Z", so a build host in any
+  // negative-offset zone (the default on many CI runners) would render
+  // "31 December 2025". DocsFooter already carries this fix; these
+  // copies dropped it.
+  return d.toLocaleDateString("en-GB", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
+// Markdown mirror for the alternate link.
+//
+// Leaf pages append `.md` to the trimmed path (`/getting-started/` →
+// `/getting-started.md`), matching the emitted `<slug>.md.ts` endpoint.
+// The SITE INDEX is the exception: it is emitted as `index.md.ts`, so
+// its mirror is `<base>/index.md`. Appending `.md` there produced
+// `/.md` (root-served) or `/blog.md` (mounted) — neither exists, and on
+// a mounted site `/blog.md` also falls outside the `/blog/*` route.
+// Both leaf and index URLs carry a trailing slash under Astro's
+// directory build format, so only "is this the site root" distinguishes
+// them. Kept in step with `shouldRewriteToMarkdown`, which is handed the
+// same combined prefix.
+// Use the `basePath` PROP, not import.meta.env.BASE_URL. Astro's `base`
+// carries only site.url's path (urlBase); the prop carries the COMBINED
+// urlBase + site.basePath prefix — the same value the middleware gets —
+// so on a `site.basePath: /docs` deploy the two would otherwise disagree
+// about which page is the index.
+const mdMirrorBase = (basePath ?? "").replace(/\/+$/, "");
+const mdMirrorPath = Astro.url.pathname.replace(/\/$/, "");
 const mdMirrorHref = mdMirror
-  ? (Astro.url.pathname.replace(/\/$/, "") || "") + ".md"
+  ? mdMirrorPath === mdMirrorBase
+    ? `${mdMirrorBase}/index.md`
+    : `${mdMirrorPath}.md`
   : undefined;
 
 // Tag keywords for HTML meta + JSON-LD. Slug-based identifiers
@@ -614,6 +711,50 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{title} | {siteName}</title>
 
+    <style is:global>
+      /*
+        The sticky-chrome contract. This header is exactly this tall, and
+        anything else that sticks (the release-comparison toolbar) offsets
+        by the same variable — so they cannot drift apart.
+      */
+      :root {
+        --db-header-height: 3rem;
+      }
+
+      /*
+        Internal/external link icons. Opt-in via `content.linkIcons`,
+        which sets `data-link-icons` (which kinds are active) and the
+        `--db-link-icon-*` custom props (the glyphs) on <body>. Links are
+        classified purely by href shape, so it covers both structured
+        links and raw-HTML anchors from imported content. Scoped to
+        `.docs-prose` so nav/header/footer links are untouched.
+      */
+      body[data-link-icons~="external"] .docs-prose a[href^="http://" i]::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="https://" i]::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="//"]::after {
+        content: var(--db-link-icon-external, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+      body[data-link-icons~="internal"]
+        .docs-prose
+        a[href^="/"]:not([href^="//"])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="./"]::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="../"]::after {
+        content: var(--db-link-icon-internal, "");
+        display: inline-block;
+        margin-inline-start: 0.15em;
+        font-size: 0.85em;
+        line-height: 1;
+        vertical-align: baseline;
+        opacity: 0.7;
+      }
+    </style>
+
     {metaDescription && <meta name="description" content={metaDescription} />}
     {favicon && <link rel="icon" href={favicon} />}
     {themeColor && <meta name="theme-color" content={themeColor} />}
@@ -708,8 +849,19 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
   <body
     class="bg-background text-foreground antialiased"
     data-pagefind-ignore={excludeFromSearch ? "" : undefined}
+    data-link-icons={_linkIconTokens || undefined}
+    style={_linkIconStyle || undefined}
   >
     <SidebarProvider>
+      {/*
+        chrome="blog" drops the sidebar COLUMN only. SidebarProvider and
+        SidebarInset stay, so the content column, header offset and
+        sticky contract are byte-identical to a docs page — which is what
+        makes the blog read as the same site rather than a lookalike.
+        With no <Sidebar> sibling the inset's peer-* selectors simply do
+        not match and it fills the width.
+      */}
+      {chrome === "docs" && (
       <Sidebar collapsible="icon">
         <SidebarHeader>
           <SidebarMenu>
@@ -742,6 +894,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 <DocsNavClient
                   currentPath={currentPath}
                   basePath={basePath ?? ""}
+                  namespace={multiSource?.namespace}
                   version={multiSource?.version}
                   locale={multiSource?.locale}
                 />
@@ -755,6 +908,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   <SidebarNavTree
                     items={filterNavByAxis(group.items, {
                       basePath: basePath ?? "/docs",
+                      namespace: multiSource?.namespace,
                       version: multiSource?.version,
                       locale: multiSource?.locale,
                     })}
@@ -769,6 +923,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 <SidebarNavTree
                   items={filterNavByAxis(nav, {
                     basePath: basePath ?? "/docs",
+                    namespace: multiSource?.namespace,
                     version: multiSource?.version,
                     locale: multiSource?.locale,
                   })}
@@ -781,10 +936,17 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
 
         <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" />
+        {/*
+          Height comes from `--db-header-height` (declared on :root in
+          <head>) — the CONTRACT any other sticky chrome offsets by, e.g.
+          the release-comparison toolbar. One variable, so a change here
+          can never leave another sticky bar overlapping or floating.
+        */}
+        <header class="sticky top-0 z-40 flex h-[var(--db-header-height)] shrink-0 items-center gap-2 border-b bg-background/95 px-4 backdrop-blur-sm supports-[backdrop-filter]:bg-background/60">
+          {chrome === "docs" && <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">
@@ -827,6 +989,8 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 pagefindUrl={pagefindUrl}
                 navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
+                scopeProduct={multiSource?.namespace}
+                scopeVersion={multiSource?.version}
               />
             )}
             {repoUrl && (
@@ -891,6 +1055,18 @@ 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>}
+            {/*
+              Multi-source axis filters — so search on a versioned/multi-
+              product site can be scoped to (or faceted by) the current
+              product and version. `product` = namespace, `version` = the
+              version segment. Only emitted when the axis is active.
+            */}
+            {multiSource?.namespace && (
+              <div hidden data-pagefind-filter={`product:${multiSource.namespace}`}></div>
+            )}
+            {multiSource?.version && (
+              <div hidden data-pagefind-filter={`version:${multiSource.version}`}></div>
+            )}
             {/*
               Custom-taxonomy filters. Any taxonomy declared in
               `dogsbay.config.yml` that isn't one of the five built-ins
@@ -944,12 +1120,62 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   {title}
                 </h1>
               )}
+              {/*
+                Byline — blog chrome only, and only when there is
+                something to say. An absent author means NO byline row,
+                never "Unknown": a placeholder byline is worse than none,
+                because it reads as data rather than as a gap.
+
+                Sits between the H1 and the lede so the reader gets
+                attribution before the summary, which is the order a
+                post is scanned in.
+              */}
+              {chrome === "blog" && (author?.length || publishedDate || readingMinutes) && (
+                <div
+                  class="not-prose mb-6 flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground"
+                  data-post-byline
+                  data-pagefind-ignore
+                >
+                  {author && author.length > 0 && (
+                    <span class="font-medium text-foreground">{author.join(", ")}</span>
+                  )}
+                  {author && author.length > 0 && publishedDate && (
+                    <span aria-hidden="true">&middot;</span>
+                  )}
+                  {publishedDate && (
+                    <time datetime={publishedDate}>{_formatPostDate(publishedDate)}</time>
+                  )}
+                  {publishedDate && readingMinutes && <span aria-hidden="true">&middot;</span>}
+                  {readingMinutes && <span>{readingMinutes} min read</span>}
+                  {updatedDate && updatedDate !== publishedDate && (
+                    <span>
+                      &middot; Updated <time datetime={updatedDate}>{_formatPostDate(updatedDate)}</time>
+                    </span>
+                  )}
+                </div>
+              )}
+
               {autoLede && description && (
                 <p class="text-lg text-muted-foreground mb-6">
                   {description}
                 </p>
               )}
 
+              {/*
+                Hero image. aspect-boxed on purpose — an unsized image
+                above the fold is the classic layout-shift source, and it
+                would shove the prose down after paint.
+              */}
+              {chrome === "blog" && heroImage && (
+                <img
+                  src={heroImage}
+                  alt=""
+                  class="not-prose mb-8 w-full rounded-lg border border-border object-cover aspect-[2/1]"
+                  loading="eager"
+                  decoding="async"
+                />
+              )}
+
               {hasMetaStrip && (
                 <div
                   class="not-prose mb-6 flex flex-wrap items-center gap-2"
@@ -996,6 +1222,12 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 lastUpdated={lastUpdated}
                 prev={prev}
                 next={next}
+                {/*
+                  Blog adjacency is chronological, so "Previous/Next"
+                  would describe the wrong axis — prev is the NEWER post.
+                */}
+                prevLabel={chrome === "blog" ? "Newer" : undefined}
+                nextLabel={chrome === "blog" ? "Older" : undefined}
                 copyright={copyright}
                 llmsLink={llmFooterLink}
                 llmsLinkHref={llmsLinkHrefResolved}

package/src/DocsNavClient.astro

@@ -17,7 +17,10 @@
  *   - 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.
+ *     link. A `sitemap-index.xml` link covers no-JS navigation —
+ *     note `emitSitemapFiles` only runs when `site.url` is a valid
+ *     http(s) URL, so a site without one has no sitemap for this
+ *     fallback to reach.
  *   - 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.
@@ -34,21 +37,32 @@ interface Props {
    * so multi-axis sites work the same as SSR.
    */
   basePath?: string;
+  /** Current source's product/namespace, if multi-product site. */
+  namespace?: 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 { currentPath, basePath = "", namespace, version, locale } = Astro.props;
 const navUrl = `${basePath}/_dogsbay/nav.json`;
 ---
 
+{/*
+  `role="navigation"` is REQUIRED here, not decoration: `aria-label` and
+  `aria-busy` are prohibited on a generic div (axe: aria-prohibited-attr,
+  serious) because a role-less element has no accessible name to label.
+  Giving the nav container its real role makes both attributes legal and
+  makes the landmark discoverable — it was previously neither.
+*/}
 <div
   id="docs-nav-root"
+  role="navigation"
   data-nav-url={navUrl}
   data-current-path={currentPath}
   data-base-path={basePath}
+  data-namespace={namespace ?? ""}
   data-version={version ?? ""}
   data-locale={locale ?? ""}
   aria-busy="true"
@@ -73,7 +87,11 @@ const navUrl = `${basePath}/_dogsbay/nav.json`;
   <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>
+      {/* sitemap-index.xml, not sitemap.xml — Dogsbay emits the
+          sitemap-index / sitemap-0 pair directly (see emitSitemapFiles);
+          `sitemap.xml` has never existed, so this no-JS fallback link
+          404'd on every site. */}
+      <a href={`${basePath}/sitemap-index.xml`} class="underline">sitemap</a>
       to browse all pages.
     </p>
   </noscript>

package/src/SearchDialog.astro

@@ -57,6 +57,14 @@ interface Props {
    * back to slugs when undefined.
    */
   taxonomyDisplay?: Record<string, TaxonomyDisplay>;
+  /**
+   * Current page's product (namespace) and version. On a multi-product /
+   * versioned site, search opens PRE-SCOPED to these — a Calico 3.32 page
+   * searches Calico 3.32 by default. The scope is seeded as normal facet
+   * selections, so the reader can untick them to search wider.
+   */
+  scopeProduct?: string;
+  scopeVersion?: string;
 }
 
 const {
@@ -64,6 +72,8 @@ const {
   navUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
+  scopeProduct,
+  scopeVersion,
 } = Astro.props;
 ---
 
@@ -72,6 +82,8 @@ const {
   data-pagefind-url={pagefindUrl}
   data-nav-url={navUrl}
   data-taxonomy-display={taxonomyDisplay ? JSON.stringify(taxonomyDisplay) : ""}
+  data-scope-product={scopeProduct ?? ""}
+  data-scope-version={scopeVersion ?? ""}
   class="fixed left-1/2 top-[10vh] z-50 w-[calc(100vw-2rem)] max-w-4xl -translate-x-1/2 rounded-xl border border-border bg-popover p-0 text-popover-foreground shadow-2xl backdrop:bg-black/40 backdrop:backdrop-blur-sm"
 >
   <form method="dialog" class="flex flex-col">
@@ -215,6 +227,9 @@ const {
   };
 
   const dialog = document.querySelector<HTMLDialogElement>("[data-search-dialog]");
+  // Current page's product/version — search opens pre-scoped to these.
+  const scopeProduct = dialog?.dataset.scopeProduct || "";
+  const scopeVersion = dialog?.dataset.scopeVersion || "";
   const trigger = document.querySelector<HTMLButtonElement>("[data-search-trigger]");
   const input = dialog?.querySelector<HTMLInputElement>("[data-search-input]");
   const resultsBox = dialog?.querySelector<HTMLDivElement>("[data-search-results]");
@@ -652,9 +667,22 @@ const {
       const fromUrl = parseFiltersFromUrl(new URLSearchParams(window.location.search));
       input!.value = fromUrl.query;
       filters = fromUrl.filters;
+      const hadUrlState = fromUrl.query.length > 0 || countActiveFilters(filters) > 0;
+      // Auto-scope: a FRESH open (no filters/query carried in the URL) on a
+      // multi-product/versioned site starts scoped to the CURRENT product +
+      // version. Seeded as ordinary facet selections, so the reader can
+      // untick "Product: calico" / "Version: 3.32" to search wider. A URL
+      // that already carries state wins (shared/roundtripped searches).
+      if (!hadUrlState) {
+        if (scopeProduct) filters.product = [scopeProduct];
+        if (scopeVersion) filters.version = [scopeVersion];
+      }
       renderFacets();
 
-      const hasInitial = input!.value.length > 0 || countActiveFilters(filters) > 0;
+      // Run immediately only when there's a query or the state came from the
+      // URL. A fresh open shows the empty prompt with the scope pre-ticked —
+      // results appear (scoped) as soon as the reader types.
+      const hasInitial = hadUrlState;
       if (hasInitial) {
         runSearch(input!.value);
       } else {

package/src/VersionSwitcher.astro

@@ -37,6 +37,9 @@ const currentLabel = currentRow?.entry.label ?? currentRow?.entry.id ?? "Version
       {currentRow?.entry.eol && (
         <span class="ml-1 rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">EOL</span>
       )}
+      {currentRow?.entry.prerelease && (
+        <span class="ml-1 rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">Pre</span>
+      )}
       <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="ml-1 transition-transform"><polyline points="6 9 12 15 18 9"/></svg>
     </summary>
     <ul class="absolute right-0 z-50 mt-1 min-w-[10rem] rounded-md border border-border bg-popover p-1 text-sm shadow-md">
@@ -59,6 +62,9 @@ const currentLabel = currentRow?.entry.label ?? currentRow?.entry.id ?? "Version
               {row.entry.eol && (
                 <span class="rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">EOL</span>
               )}
+              {row.entry.prerelease && (
+                <span class="rounded bg-muted px-1 text-[10px] uppercase text-muted-foreground">Pre</span>
+              )}
               {row.entry.default && !row.isCurrent && (
                 <span class="text-[10px] text-muted-foreground">default</span>
               )}

package/src/docs-nav-client.ts

@@ -23,11 +23,63 @@
  */
 import { filterNavByAxis } from "./nav-filter.js";
 
+interface NavMark {
+  kind: "added" | "changed" | "removed" | "moved";
+  label?: string;
+  subtree?: boolean;
+}
+
 interface NavItem {
   label: string;
   href?: string;
   icon?: string;
   children?: NavItem[];
+  mark?: NavMark;
+}
+
+/**
+ * A state marker beside a nav label (release comparisons mark changed /
+ * new / removed pages; the same slot serves "new since your last
+ * visit", deprecation flags, version badges).
+ *
+ * Accessibility contract — mirrors SidebarNavMark.astro, which renders
+ * the server-side tree:
+ *  - **Never colour alone** (WCAG 1.4.1): a distinct GLYPH carries the
+ *    meaning, so it survives greyscale and colour-blindness; colour only
+ *    reinforces.
+ *  - **Survives forced-colors** (High Contrast strips backgrounds): the
+ *    glyph is real text, so it always renders.
+ *  - **Announced**: a visually-hidden word rides along, so the row reads
+ *    "MySQL, changed". It is a sibling span, NOT an aria-label on the
+ *    link — an aria-label would REPLACE the page name in the
+ *    accessibility tree, losing the label it exists to announce.
+ */
+const MARK_GLYPH: Record<NavMark["kind"], string> = {
+  added: "+",
+  changed: "•",
+  removed: "−",
+  moved: "→",
+};
+
+function buildMark(mark: NavMark): HTMLElement {
+  const text = mark.label ?? (mark.subtree ? `contains ${mark.kind}` : mark.kind);
+  const wrap = document.createElement("span");
+  wrap.className = "db-nav-mark";
+  wrap.dataset.navMark = mark.kind;
+  if (mark.subtree) wrap.dataset.navMarkSubtree = "";
+  wrap.title = text;
+
+  const glyph = document.createElement("span");
+  glyph.setAttribute("aria-hidden", "true");
+  glyph.textContent = MARK_GLYPH[mark.kind];
+  wrap.appendChild(glyph);
+
+  const sr = document.createElement("span");
+  sr.className = "sr-only";
+  sr.textContent = text;
+  wrap.appendChild(sr);
+
+  return wrap;
 }
 
 /**
@@ -123,6 +175,14 @@ export function renderItem(item: NavItem, current: string, level: number): HTMLL
     if (active) link.dataset.active = "true";
     row.appendChild(link);
 
+    if (item.mark) {
+      // A SUBTREE mark describes DESCENDANTS — never strike through this
+      // row for it (a surviving group whose child was deleted would read
+      // as a deleted section).
+      if (!item.mark.subtree) link.dataset.navMarkRow = item.mark.kind;
+      row.appendChild(buildMark(item.mark));
+    }
+
     const submenu = document.createElement("ul");
     submenu.id = submenuId;
     submenu.dataset.navSubmenu = "";
@@ -173,6 +233,11 @@ export function renderItem(item: NavItem, current: string, level: number): HTMLL
     label.textContent = item.label;
     summary.appendChild(label);
 
+    // A collapsed group HIDES its children, so a change inside must
+    // signal outward — the same visibility rule the diff renderer
+    // applies to tabs.
+    if (item.mark) summary.appendChild(buildMark(item.mark));
+
     details.appendChild(summary);
 
     const childUl = document.createElement("ul");
@@ -212,10 +277,17 @@ export function renderItem(item: NavItem, current: string, level: number): HTMLL
     }
 
     const label = document.createElement("span");
-    label.className = "truncate";
+    label.className = "min-w-0 flex-1 truncate";
     label.textContent = item.label;
     a.appendChild(label);
 
+    if (item.mark) {
+      // strikethrough only for a page that IS removed, never for an
+      // aggregate about its children
+      if (!item.mark.subtree) a.dataset.navMarkRow = item.mark.kind;
+      a.appendChild(buildMark(item.mark));
+    }
+
     li.appendChild(a);
   }
 
@@ -304,13 +376,20 @@ export async function hydrateDocsNav(): Promise<void> {
   }
   const current = normalize(root.dataset.currentPath || location.pathname);
   const basePath = root.dataset.basePath || "";
+  const namespace = root.dataset.namespace || undefined;
   const version = root.dataset.version || undefined;
   const locale = root.dataset.locale || undefined;
 
   try {
     const nav = await fetchNav(navUrl);
     const filtered = filterNavByAxis(nav, {
-      basePath: basePath || "/docs",
+      // Pass basePath through as-is — an empty basePath (root-served
+      // site) must stay "", matching the SSR path's `?? "/docs"`
+      // (which keeps ""). Coercing "" → "/docs" makes the filter look
+      // for `/docs/…` bucket hrefs that don't exist and blanks the
+      // whole sidebar on a root-served multi-source site.
+      basePath,
+      namespace: namespace || undefined,
       version: version || undefined,
       locale: locale || undefined,
     });

package/src/link-icons.ts

@@ -0,0 +1,54 @@
+/**
+ * Internal/external link-icon affordance — the tiny bit of logic behind
+ * the `data-link-icons` + `--db-link-icon-*` attributes DocsLayout stamps
+ * on `<body>`. Classification itself is pure CSS (by href shape); this
+ * only turns the configured glyphs into the attribute + custom-property
+ * values. See plans/link-resolution-and-icons.md.
+ */
+
+export interface LinkIcons {
+  /** Glyph after external links (absolute / protocol-relative href). */
+  external?: string;
+  /** Glyph after internal links (root / relative href). */
+  internal?: string;
+}
+
+export interface LinkIconAttrs {
+  /**
+   * Space-separated active kinds for `data-link-icons` (`"external"`,
+   * `"internal"`, or both) — undefined when the feature is off, so the
+   * attribute is omitted entirely.
+   */
+  tokens?: string;
+  /**
+   * Inline `style` value setting the `--db-link-icon-*` custom
+   * properties to the (single-quoted, CSS-string-safe) glyphs —
+   * undefined when nothing is active.
+   */
+  style?: string;
+}
+
+/** CSS-string-escape a glyph so it's a valid single-quoted `content:` value. */
+function cssString(glyph: string): string {
+  return glyph.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+/**
+ * Build the `<body>` attributes for the link-icon feature. A side is
+ * active only when its glyph is a non-empty string; an absent config (or
+ * all-empty) yields `{}` so DocsLayout emits no attributes.
+ */
+export function linkIconAttrs(icons: LinkIcons | undefined): LinkIconAttrs {
+  const external = icons?.external?.trim() ? icons.external : "";
+  const internal = icons?.internal?.trim() ? icons.internal : "";
+  const tokens = [external ? "external" : "", internal ? "internal" : ""]
+    .filter(Boolean)
+    .join(" ");
+  const style = [
+    external ? `--db-link-icon-external: '${cssString(external)}'` : "",
+    internal ? `--db-link-icon-internal: '${cssString(internal)}'` : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+  return { tokens: tokens || undefined, style: style || undefined };
+}

package/src/markdown-negotiation.ts

@@ -7,6 +7,11 @@
  * Returns the path to rewrite to (the `.md` mirror endpoint) when the
  * request should be served as markdown; returns `null` when the normal
  * HTML response should pass through.
+ *
+ * `basePath` is the prefix the site is SERVED at (Dogsbay's combined
+ * urlBase + basePath). It is needed only to recognise the site index,
+ * whose mirror is `<base>/index.md` rather than `<base>.md` — see
+ * `shouldRewriteToMarkdown`.
  */
 
 const Q_PARAM_RE = /^\s*q\s*=\s*([0-9.]+)\s*$/i;
@@ -28,6 +33,7 @@ const Q_PARAM_RE = /^\s*q\s*=\s*([0-9.]+)\s*$/i;
 export function shouldRewriteToMarkdown(
   accept: string | null | undefined,
   pathname: string,
+  basePath = "",
 ): string | null {
   if (!accept) return null;
   if (!acceptsMarkdown(accept)) return null;
@@ -35,8 +41,38 @@ export function shouldRewriteToMarkdown(
   if (hasNonHtmlExtension(pathname)) return null;
 
   const trimmed = pathname.replace(/\/$/, "");
-  const target = trimmed === "" ? "/.md" : `${trimmed}.md`;
-  return target;
+  const base = basePath.replace(/\/+$/, "");
+
+  // A request outside the served prefix is not ours to rewrite. Without
+  // this guard, `("/", "/docs")` fell through to `"" + ".md"` — a
+  // RELATIVE target, resolved against whatever the request path was.
+  if (base && trimmed !== base && !trimmed.startsWith(`${base}/`)) return null;
+
+  // The site index is emitted as `index.md.ts`, so its mirror is
+  // `<base>/index.md`. Every other page emitted by the shipped importers
+  // has its mirror at `<path>.md`: Dogsbay builds in Astro's directory
+  // format, so a leaf at `/getting-started/` maps to
+  // `/getting-started.md`, and a directory index like `guides/index.md`
+  // is NORMALIZED to slug `guides` (see import-mkdocs.ts's
+  // `.replace(/\/index$/, "")`), emitting `guides.astro` + `guides.md.ts`
+  // — so `/guides.md` exists too.
+  //
+  // Appending `.md` to the site index produced `/.md` (root-served) or
+  // `/blog.md` (mounted); neither exists, and `/blog.md` additionally
+  // falls OUTSIDE the `/blog/*` Workers route. Leaf and index URLs both
+  // carry a trailing slash, so only the base comparison distinguishes
+  // them.
+  //
+  // CAVEAT: a caller driving `exportAstroProject` directly with an
+  // unnormalized `<dir>/index` slug gets `src/pages/<dir>/index.astro`
+  // (served `/<dir>/`) whose only mirror is `/<dir>/index.md`, and this
+  // returns `/<dir>.md` — a 404. No shipped importer does that. If one
+  // ever should, generalize the sibling `.md.ts` emitter in
+  // `format-astro/src/project.ts` rather than guessing here from a URL
+  // that cannot distinguish the two shapes.
+  if (trimmed === base) return `${base}/index.md`;
+
+  return `${trimmed}.md`;
 }
 
 function acceptsMarkdown(accept: string): boolean {

package/src/nav-filter.ts

@@ -1,18 +1,17 @@
 /**
  * Multi-source nav filtering.
  *
- * When a docs site has multiple versions (or, in PR 5, locales)
- * configured, every page's emitted nav.json contains entries
- * from EVERY version. Without filtering, the sidebar shows
- * duplicate sections — once per version — which is confusing
- * UX (writers see "Glossary" twice).
+ * When a docs site has multiple products/versions/locales, every page's
+ * emitted nav.json contains entries from EVERY bucket. Without filtering,
+ * the sidebar shows a product's sections once per version, and every other
+ * product too — confusing UX. The fix: filter the nav tree to the current
+ * page's (namespace, locale, version) bucket.
  *
- * The fix: filter the nav tree to entries that match the
- * current page's version (or, eventually, locale). Pure
- * function; takes nav + axis filter, returns a pruned copy.
- *
- * The axis switchers handle navigation BETWEEN versions; the
- * sidebar nav reflects only the active axis bucket.
+ * The match is a single COMPOSED prefix in the canonical URL order
+ * `/<basePath>/<namespace>/<locale>/<version>/...` — whichever of those
+ * axes the current page carries. The axis switchers handle navigation
+ * BETWEEN buckets; the sidebar reflects only the active one. Pure
+ * function: nav + filter → pruned copy.
  */
 
 interface NavItem {
@@ -22,145 +21,59 @@ interface NavItem {
 }
 
 export interface NavFilter {
-  /** Site basePath (e.g. "/docs"). Used to compose the version prefix. */
+  /** Site basePath (e.g. "" for root, "/docs"). */
   basePath: string;
-  /**
-   * Current page's effective version. When undefined, no
-   * version filtering is applied — single-version sites pass
-   * the full nav through unchanged.
-   */
-  version?: string;
-  /**
-   * Current page's effective locale. When set, nav items are
-   * filtered to those whose href starts with the corresponding
-   * locale segment (`<basePath>/<locale>/`).
-   */
+  /** Current page's product/namespace segment (outermost), if any. */
+  namespace?: string;
+  /** Current page's locale segment (after namespace), if any. */
   locale?: string;
+  /** Current page's version segment (innermost, next to the page), if any. */
+  version?: string;
 }
 
 /**
- * Walk the nav tree and drop entries that don't belong to the
- * current version + locale. Group nodes (no `href`, with
- * `children`) survive iff any descendant survives — empty
- * groups are pruned.
- *
- * Items without `href` AND without `children` are unusual but
- * pass through unchanged (defensive — never silently drop a
- * node we don't understand).
- *
- * Both filters apply concurrently: a multi-version multi-locale
- * site filters by BOTH simultaneously, so an item must match
- * /<basePath>/<locale>/.../<version>/... structurally.
+ * Prune the nav to the current page's bucket. Group nodes (no `href`,
+ * with `children`) survive iff a descendant survives; empty groups and
+ * childless/href-less nodes are dropped (else a non-current bucket's group
+ * lingers as a phantom header).
  */
-export function filterNavByAxis(
-  items: NavItem[],
-  filter: NavFilter,
-): NavItem[] {
-  if (!filter.version && !filter.locale) return items;
+export function filterNavByAxis(items: NavItem[], filter: NavFilter): NavItem[] {
+  // Canonical order: namespace → locale → version. Only the axes the
+  // current page actually carries contribute to the match prefix.
+  const segs = [filter.namespace, filter.locale, filter.version].filter(
+    (s): s is string => s !== undefined && s !== "",
+  );
+  if (segs.length === 0) return items;
 
-  // Locale axis prefix is the OUTERMOST per the canonical URL
-  // composition: /<basePath>/<locale>/<version>/<ns>/<slug>.
-  // We check the locale prefix first (basePath/<locale>/), then
-  // (when version is also active) check that <version> is the
-  // immediately-following segment.
-  const localePrefix = filter.locale
-    ? prefixFor(filter.basePath, filter.locale)
-    : null;
-  const versionSegment = filter.version ?? null;
+  const base = filter.basePath.replace(/\/$/, "");
+  const prefix = `${base}/${segs.join("/")}/`;
+  const prefixNoSlash = prefix.replace(/\/$/, "");
 
-  return items.flatMap((item) =>
-    filterOne(item, localePrefix, versionSegment, filter.basePath),
-  );
+  return items.flatMap((item) => filterOne(item, prefix, prefixNoSlash));
 }
 
-function filterOne(
-  item: NavItem,
-  localePrefix: string | null,
-  versionSegment: string | null,
-  basePath: string,
-): NavItem[] {
+function filterOne(item: NavItem, prefix: string, prefixNoSlash: string): NavItem[] {
   if (item.children && item.children.length > 0) {
-    const kept = item.children.flatMap((c) =>
-      filterOne(c, localePrefix, versionSegment, basePath),
-    );
+    const kept = item.children.flatMap((c) => filterOne(c, prefix, prefixNoSlash));
     if (kept.length === 0) return [];
     return [{ ...item, children: kept }];
   }
   if (item.href !== undefined) {
-    if (!hrefMatchesAxes(item.href, localePrefix, versionSegment, basePath)) {
-      return [];
-    }
-    return [item];
+    return hrefMatchesPrefix(item.href, prefix, prefixNoSlash) ? [item] : [];
   }
-  return [item];
-}
-
-/**
- * Check that an href belongs to the requested (locale, version)
- * combination. Either prefix can be null — meaning that axis
- * isn't being filtered.
- */
-function hrefMatchesAxes(
-  href: string,
-  localePrefix: string | null,
-  versionSegment: string | null,
-  basePath: string,
-): boolean {
-  // External URLs aren't axis-bucketed.
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
-    return false;
-  }
-
-  // Step 1: locale check. If locale axis is active, the href
-  // must be inside /<basePath>/<locale>/.
-  if (localePrefix !== null) {
-    if (!hrefMatchesPrefix(href, localePrefix)) return false;
-  }
-
-  // Step 2: version check. The version segment is positioned
-  // AFTER the locale segment when both are active, otherwise
-  // immediately after basePath.
-  if (versionSegment !== null) {
-    const baseTrimmed = basePath.replace(/\/$/, "");
-    const localeSegStart = localePrefix
-      ? localePrefix.replace(/\/$/, "")
-      : baseTrimmed;
-    const versionPrefix = `${localeSegStart}/${versionSegment}/`;
-    const versionPrefixNoSlash = versionPrefix.replace(/\/$/, "");
-    if (
-      !href.startsWith(versionPrefix) &&
-      href !== versionPrefixNoSlash
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Compose the URL prefix for a given version under the
- * configured basePath. Always ends in `/` so prefix-matching
- * doesn't accept partial segments (`/docs/v1` shouldn't match
- * `/docs/v10/...`).
- */
-function prefixFor(basePath: string, segment: string): string {
-  const base = basePath.replace(/\/$/, "");
-  return `${base}/${segment}/`;
+  // Childless AND href-less: no navigation, no bucket membership. In a
+  // filtered view it must be dropped.
+  return [];
 }
 
 /**
- * Whether an href belongs to the given version prefix. Tolerates
- * trailing slashes and missing-trailing-slash variants — nav
- * importers don't all canonicalise the same way.
+ * Whether an href belongs to the composed bucket prefix. Tolerates the
+ * bucket's landing page itself (`/<prefix>` with no trailing slash);
+ * external URLs never match.
  */
-function hrefMatchesPrefix(href: string, prefix: string): boolean {
-  // Skip external URLs.
+function hrefMatchesPrefix(href: string, prefix: string, prefixNoSlash: string): boolean {
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
     return false;
   }
-  // Match `/docs/v1/...` AND `/docs/v1` (the version's landing
-  // page itself, if a writer linked to it directly).
-  const trimmedPrefix = prefix.replace(/\/$/, "");
-  return href.startsWith(prefix) || href === trimmedPrefix;
+  return href.startsWith(prefix) || href === prefixNoSlash;
 }

package/src/switcher.ts

@@ -11,6 +11,14 @@ export interface AxisEntry {
   id: string;
   label?: string;
   eol?: boolean;
+  /** Pre-release mark (version axis only) — the moving next/beta head. */
+  prerelease?: boolean;
+  /**
+   * Served but kept OFF the switcher (version axis only). Marks the number
+   * a `latest` alias points at, so the dropdown shows one "3.32 (latest)"
+   * row instead of both "latest" and "3.32".
+   */
+  hidden?: boolean;
   default?: boolean;
 }
 
@@ -73,9 +81,32 @@ export interface BuildRowsInput {
   multiSource: MultiSourceMeta;
 }
 
+/**
+ * Order two version ids. Compares numeric components left-to-right
+ * (`3.32` > `3.31`, `3.23-2` > `3.23-1`); a non-numeric alias (`latest`,
+ * `next`) sorts ABOVE any numbered version so descending order puts it
+ * first. When NEITHER id has any digits — a non-semver / codename scheme
+ * (`Boron`, `Argon`) — returns 0 so the sort is a no-op and the author's
+ * DECLARED order is preserved (JS sort is stable), rather than silently
+ * alphabetising and putting the newest release at the bottom.
+ */
+export function compareVersionIds(a: string, b: string): number {
+  const na = (a.match(/\d+/g) ?? []).map(Number);
+  const nb = (b.match(/\d+/g) ?? []).map(Number);
+  if (na.length === 0 && nb.length === 0) return 0; // codenames → keep declared order
+  if (na.length === 0) return 1; // alias > number
+  if (nb.length === 0) return -1;
+  const len = Math.max(na.length, nb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (na[i] ?? 0) - (nb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return a.localeCompare(b);
+}
+
 export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
   const { axis, switcherMap, multiSource } = input;
-  const entries = axis === "version" ? switcherMap.versions : switcherMap.locales;
+  const allEntries = axis === "version" ? switcherMap.versions : switcherMap.locales;
   const currentId =
     axis === "version" ? multiSource.version : multiSource.locale;
   const otherAxis: SwitcherAxis = axis === "version" ? "locale" : "version";
@@ -84,6 +115,56 @@ export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
 
   const variants = switcherMap.byLogicalKey[logicalKeyFor(multiSource)] ?? [];
 
+  // On a MULTI-PRODUCT (namespace-active) site the declared version list
+  // is the UNION across products, but a page's variants are same-namespace
+  // (the logical key is namespaced). Scope the version switcher to the
+  // versions this page's product actually has, so a Calico page never
+  // offers a Calico-Enterprise version. Single-product sites (no
+  // namespace) keep the full declared list, with fallbacks for pages
+  // missing in some version.
+  let entries = allEntries;
+  if (axis === "version" && multiSource.namespace !== undefined) {
+    const available = new Set(
+      variants.map((v) => v.version).filter((v): v is string => v !== undefined),
+    );
+    entries = allEntries.filter((e) => available.has(e.id) || e.id === currentId);
+  }
+
+  // The version dropdown always reads newest → oldest (3.32, 3.31, …),
+  // regardless of the declared order. Aliases (e.g. "latest") that don't
+  // parse as versions sort to the top, ahead of the numbers.
+  //
+  // `latest` alias + its target: a version marked `hidden` is the number
+  // the `latest` alias points at (Docusaurus's lastVersion). Show ONE row
+  // "3.32 (latest)" (linking to /latest/), derive its label from the hidden
+  // sibling, and drop hidden rows from the dropdown.
+  //
+  // The hidden number is DECLARED but NOT SERVED: `migrate-docusaurus
+  // --latest-alias` emits one source for the newest branch, at `latest`.
+  // That mirrors the source, where `versions: { "3.32": { path: "latest" } }`
+  // REPLACES the segment — docs.tigera.io has /calico/latest/ and no
+  // /calico/3.32/. Serving both invented a URL tree the source never had
+  // and duplicated every page of the newest release (338 on Calico) with
+  // no canonical. So the hidden entry is label-only metadata.
+  //
+  // `currentFoldedIntoLatest` still matters for a corpus that DOES serve
+  // the number (a hand-written config may), so a reader on `/3.32/…` has
+  // the merged `latest` row highlighted rather than no row at all. No
+  // `hidden` sibling → no merge.
+  let currentFoldedIntoLatest = false;
+  if (axis === "version") {
+    entries = [...entries].sort((a, b) => compareVersionIds(b.id, a.id));
+    const hiddenTarget = entries.find((e) => e.hidden && /\d/.test(e.id));
+    currentFoldedIntoLatest = hiddenTarget?.id === currentId;
+    entries = entries
+      .filter((e) => !e.hidden)
+      .map((e) =>
+        e.id === "latest" && hiddenTarget
+          ? { ...e, label: `${hiddenTarget.label ?? hiddenTarget.id} (latest)` }
+          : e,
+      );
+  }
+
   return entries.map((entry) => {
     const match = variants.find((v) => {
       // Match on this axis.
@@ -98,7 +179,7 @@ export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
     return {
       entry,
       url: match?.url ?? null,
-      isCurrent: entry.id === currentId,
+      isCurrent: entry.id === currentId || (entry.id === "latest" && currentFoldedIntoLatest),
     };
   });
 }