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

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;
 }