@dogsbay/docs-layout 0.2.0-beta.114 → 0.2.0-beta.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.114",
+  "version": "0.2.0-beta.116",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -25,13 +25,15 @@
     "./LocaleSwitcher.astro": "./src/LocaleSwitcher.astro",
     "./nav-filter": "./src/nav-filter.ts",
     "./search-facets": "./src/search-facets.ts",
+    "./pagefind-base-url": "./src/pagefind-base-url.ts",
     "./tag-list-data": "./src/tag-list-data.ts",
     "./llm-actions": "./src/llm-actions.ts",
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/primitives": "0.2.0-beta.114",
-    "@dogsbay/ui": "0.2.0-beta.114"
+    "@dogsbay/primitives": "0.2.0-beta.116",
+    "@dogsbay/ui": "0.2.0-beta.116",
+    "@dogsbay/site-files": "0.2.0-beta.116"
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",

package/src/DocsLayout.astro

@@ -45,7 +45,7 @@ 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 { filterNavByAxis, rootVersionFilter } from "./nav-filter.js";
 import type { LlmProviderName } from "./llm-actions.js";
 import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd, buildWebSiteJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
@@ -89,6 +89,8 @@ type TagPaletteName =
 interface Props {
   /** Site name shown in header and sidebar logo */
   siteName: string;
+  /** The line under the site name in the sidebar header (`site.tagline`). Default "Documentation". */
+  siteTagline?: string;
   /** Page title for <title> tag */
   title: string;
   /** Home URL — also used as the base for the canonical link if absolute */
@@ -131,6 +133,10 @@ interface Props {
   ogType?: "article" | "website";
   /** Canonical URL for this page. Auto-computed from siteUrl + pathname when absolute siteUrl is provided. */
   canonicalUrl?: string;
+  /** `hreflang` alternates for this page's copies in other languages (absolute URLs), written after the canonical link. */
+  alternates?: { hreflang: string; href: string }[];
+  /** JSON-LD `BreadcrumbList` for this page, written after its own JSON-LD block. */
+  breadcrumbJsonLd?: Record<string, unknown>;
   /** Twitter / X handle including the leading "@" */
   twitterHandle?: string;
   /** Theme color hint for browsers (hex string) */
@@ -197,6 +203,12 @@ interface Props {
    * a non-root base path (e.g. "/docs/pagefind/").
    */
   pagefindUrl?: string;
+  /**
+   * Base Pagefind prefixes result URLs with. Forwarded to SearchDialog;
+   * format-astro passes the right value for the deploy layout. See
+   * `pagefind-base-url.ts` for why no constant works.
+   */
+  pagefindBaseUrl?: string;
   /**
    * Whether the site emits per-page `.md` mirror endpoints. When true,
    * the page advertises `<link rel="alternate" type="text/markdown">`
@@ -231,6 +243,12 @@ interface Props {
    * `taxonomies.tags.labels`.
    */
   tagLabels?: Record<string, string>;
+  /**
+   * Color chips whose prefix has no color automatically (a stable
+   * palette color per first segment). Sourced from
+   * `taxonomies.tags.autoColor`.
+   */
+  tagAutoColor?: boolean;
   /**
    * Page lifecycle status. Renders a StatusBadge for non-stable
    * states. Drafts/deprecated get strong colors.
@@ -351,7 +369,7 @@ interface Props {
    * `@/data/switcherMap.json`.
    */
   switcherMap?: {
-    versions: Array<{ id: string; label?: string; eol?: boolean; default?: boolean }>;
+    versions: Array<{ id: string; label?: string; eol?: boolean; default?: boolean; root?: boolean }>;
     byLogicalKey: Record<string, Record<string, string>>;
   };
   /**
@@ -467,6 +485,7 @@ interface Props {
 const {
   poweredBy = false,
   siteName,
+  siteTagline,
   title,
   siteUrl = "/",
   nav,
@@ -486,6 +505,8 @@ const {
   defaultOgImage,
   ogType = "article",
   canonicalUrl,
+  alternates = [],
+  breadcrumbJsonLd,
   twitterHandle,
   themeColor,
   noindex,
@@ -501,11 +522,13 @@ const {
   // Undefined here propagates to SearchDialog where the JS loader
   // throws on first open instead of silently 404'ing the bundle.
   pagefindUrl,
+  pagefindBaseUrl,
   mdMirror = false,
   tags,
   tagsIndexPath = "/tags",
   tagPrefixes,
   tagLabels,
+  tagAutoColor = false,
   status,
   pageType,
   audience,
@@ -532,6 +555,10 @@ const {
   class: className,
 } = Astro.props;
 
+// The version served at the site root (`path: ""`), if any: the sidebar
+// keeps its pages by leaving out the other versions' folders.
+const navRootVersion = rootVersionFilter(switcherMap?.versions);
+
 // 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).
@@ -763,11 +790,12 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         `--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.
+        `.docs-prose` so nav/header/footer links are untouched; buttons
+        (`<a data-variant>`, from Button.astro) carry no icon.
       */
-      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 {
+      body[data-link-icons~="external"] .docs-prose a[href^="http://" i]:not([data-variant])::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="https://" i]:not([data-variant])::after,
+      body[data-link-icons~="external"] .docs-prose a[href^="//"]:not([data-variant])::after {
         content: var(--db-link-icon-external, "");
         display: inline-block;
         margin-inline-start: 0.15em;
@@ -778,9 +806,9 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
       }
       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 {
+        a[href^="/"]:not([href^="//"]):not([data-variant])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="./"]:not([data-variant])::after,
+      body[data-link-icons~="internal"] .docs-prose a[href^="../"]:not([data-variant])::after {
         content: var(--db-link-icon-internal, "");
         display: inline-block;
         margin-inline-start: 0.15em;
@@ -821,6 +849,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
        sidebar / header / TOC text from per-page excerpts. See main. */}
 
     {computedCanonical && <link rel="canonical" href={computedCanonical} />}
+    {alternates.map((a) => <link rel="alternate" hreflang={a.hreflang} href={a.href} />)}
     {mdMirrorHref && <link rel="alternate" type="text/markdown" href={mdMirrorHref} />}
     {/* Programmatic llms.txt discovery — agents that follow head
        link rels get the per-mount llms.txt without parsing HTML.
@@ -868,7 +897,10 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
        Schema.org keywords string; Google reads this for topical
        categorization in rich results. */}
     {articleJsonLd && (
-      <script type="application/ld+json" set:html={JSON.stringify(articleJsonLd)} />
+      <script type="application/ld+json" set:html={JSON.stringify(articleJsonLd).replace(/</g, "\\u003c")} />
+    )}
+    {breadcrumbJsonLd && (
+      <script type="application/ld+json" set:html={JSON.stringify(breadcrumbJsonLd).replace(/</g, "\\u003c")} />
     )}
 
     {/* Per-page / per-site custom structured data. Layered on
@@ -957,7 +989,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 </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>
+                  <span class="truncate text-xs text-sidebar-foreground/70">{siteTagline || "Documentation"}</span>
                 </div>
               </SidebarMenuButton>
             </SidebarMenuItem>
@@ -982,6 +1014,8 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                   namespace={multiSource?.namespace}
                   version={multiSource?.version}
                   locale={multiSource?.locale}
+                  rootVersion={navRootVersion.rootVersion}
+                  versionSegments={navRootVersion.versionSegments}
                 />
               </SidebarGroupContent>
             </SidebarGroup>
@@ -996,6 +1030,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                       namespace: multiSource?.namespace,
                       version: multiSource?.version,
                       locale: multiSource?.locale,
+                      ...navRootVersion,
                     })}
                     currentPath={currentPath}
                   />
@@ -1011,6 +1046,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                     namespace: multiSource?.namespace,
                     version: multiSource?.version,
                     locale: multiSource?.locale,
+                    ...navRootVersion,
                   })}
                   currentPath={currentPath}
                 />
@@ -1072,6 +1108,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             {!hideSearch && (
               <SearchDialog
                 pagefindUrl={pagefindUrl}
+                pagefindBaseUrl={pagefindBaseUrl}
                 navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
                 scopeProduct={multiSource?.namespace}
@@ -1284,6 +1321,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                       indexPath={tagsIndexPath}
                       prefixes={tagPrefixes}
                       labels={tagLabels}
+                      autoColor={tagAutoColor}
                     />
                   )}
                 </div>

package/src/DocsNavClient.astro

@@ -43,9 +43,13 @@ interface Props {
   version?: string;
   /** Current source's locale axis value, if multi-locale site. */
   locale?: string;
+  /** The version served at the site root (`path: ""`), if any. */
+  rootVersion?: string;
+  /** The other versions' URL segments (left out of the root version's nav). */
+  versionSegments?: string[];
 }
 
-const { currentPath, basePath = "", namespace, version, locale } = Astro.props;
+const { currentPath, basePath = "", namespace, version, locale, rootVersion, versionSegments } = Astro.props;
 const navUrl = `${basePath}/_dogsbay/nav.json`;
 ---
 
@@ -65,6 +69,8 @@ const navUrl = `${basePath}/_dogsbay/nav.json`;
   data-namespace={namespace ?? ""}
   data-version={version ?? ""}
   data-locale={locale ?? ""}
+  data-root-version={rootVersion ?? ""}
+  data-version-segments={(versionSegments ?? []).join(" ")}
   aria-busy="true"
   aria-label="Documentation navigation"
 >

package/src/SearchDialog.astro

@@ -37,6 +37,15 @@ interface Props {
    * search dialog throws on first open with a clear console error.
    */
   pagefindUrl?: string;
+  /**
+   * The base Pagefind prefixes result URLs with. Pagefind's own default is
+   * the folder above the bundle, which is right for GitHub Pages project
+   * sites and doubles the prefix on Workers subpath mounts (their index
+   * already carries the mount). format-astro computes the right value per
+   * layout; when absent, Pagefind's default is left alone. See
+   * `pagefind-base-url.ts`.
+   */
+  pagefindBaseUrl?: string;
   /**
    * URL of the site's `nav.json` (typically `${basePath}/_dogsbay/nav.json`).
    * Used to render hierarchical facets in document order: when the
@@ -69,6 +78,7 @@ interface Props {
 
 const {
   pagefindUrl,
+  pagefindBaseUrl,
   navUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
@@ -80,6 +90,7 @@ const {
 <dialog
   data-search-dialog
   data-pagefind-url={pagefindUrl}
+  data-pagefind-base-url={pagefindBaseUrl}
   data-nav-url={navUrl}
   data-taxonomy-display={taxonomyDisplay ? JSON.stringify(taxonomyDisplay) : ""}
   data-scope-product={scopeProduct ?? ""}
@@ -201,6 +212,7 @@ const {
     type NavLike,
     type TaxonomyDisplayMap,
   } from "./search-facets.js";
+  import { applyPagefindBaseUrl } from "./pagefind-base-url.js";
 
   type PagefindResult = {
     id: string;
@@ -224,6 +236,7 @@ const {
       options?: { filters?: Record<string, PagefindFilterValue> },
     ): Promise<{ results: PagefindResult[] }>;
     filters(): Promise<Record<string, Record<string, number>>>;
+    options?(opts: { baseUrl?: string }): Promise<void>;
   };
 
   const dialog = document.querySelector<HTMLDialogElement>("[data-search-dialog]");
@@ -290,6 +303,9 @@ const {
       loadingPagefind = (async () => {
         try {
           const mod = (await import(/* @vite-ignore */ url)) as PagefindModule;
+          // Before the first search: result URLs are built with this base.
+          // Without it a Workers subpath mount links to /<mount>/<mount>/page/.
+          await applyPagefindBaseUrl(mod, dialog!.dataset.pagefindBaseUrl);
           pagefind = mod;
           // Discover facets once, on first load. Pagefind builds
           // this from the body-level data-pagefind-filter elements.

package/src/TagList.astro

@@ -48,6 +48,11 @@ interface Props {
    * text. URL still uses the slug.
    */
   labels?: Record<string, string>;
+  /**
+   * Give chips whose prefix has no color a stable palette color,
+   * hashed from the tag's first segment. Default false.
+   */
+  autoColor?: boolean;
   /** Optional aria-label override; default "Tags". */
   label?: string;
   class?: string;
@@ -58,11 +63,12 @@ const {
   indexPath = "/tags",
   prefixes,
   labels,
+  autoColor = false,
   label: ariaLabel = "Tags",
   class: className,
 } = Astro.props;
 
-const chips = buildChips(tags, { indexPath, prefixes, labels });
+const chips = buildChips(tags, { indexPath, prefixes, labels, autoColor });
 
 /**
  * Closed palette → Tailwind class strings. Each entry is one

package/src/VersionSwitcher.astro

@@ -44,7 +44,7 @@ const currentLabel = currentRow?.entry.label ?? currentRow?.entry.id ?? "Version
     </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">
       {rows.map((row) => {
-        const href = row.url ?? fallbackLandingUrl(basePath, row.entry.id);
+        const href = row.url ?? fallbackLandingUrl(basePath, row.entry.id, row.entry.root === true);
         const isFallback = row.url === null && !row.isCurrent;
         return (
           <li>

package/src/docs-nav-client.ts

@@ -379,6 +379,8 @@ export async function hydrateDocsNav(): Promise<void> {
   const namespace = root.dataset.namespace || undefined;
   const version = root.dataset.version || undefined;
   const locale = root.dataset.locale || undefined;
+  const rootVersion = root.dataset.rootVersion || undefined;
+  const versionSegments = (root.dataset.versionSegments || "").split(" ").filter(Boolean);
 
   try {
     const nav = await fetchNav(navUrl);
@@ -392,6 +394,7 @@ export async function hydrateDocsNav(): Promise<void> {
       namespace: namespace || undefined,
       version: version || undefined,
       locale: locale || undefined,
+      ...(rootVersion ? { rootVersion, versionSegments } : {}),
     });
     renderTree(filtered, current, root);
   } catch (err) {

package/src/json-ld.ts

@@ -1,167 +1,6 @@
 /**
- * JSON-LD helpers — pure functions consumed by DocsLayout to
- * decide which Schema.org `@type` to emit and to normalize the
- * `customJsonLd` prop shape.
- *
- * The 100daysofdocs SEO audit flagged that DocsLayout was emitting
- * `Article` for every page regardless of intent — tutorials and
- * how-to pages should render as `HowTo` for SERP rich results.
- * This module owns the type selection so it's testable without
- * spinning up an Astro renderer.
+ * JSON-LD helpers for DocsLayout. They live in `@dogsbay/site-files`,
+ * which dogsbay-ssg uses too, so both pipelines emit the same blocks.
  */
-
-/**
- * Map a `meta.type` value (the open-string `pageType` prop on
- * DocsLayout) to a Schema.org `@type`.
- *
- * The mapping intentionally accepts a few common spelling
- * variants (`"how-to"` / `"howto"`, `"reference"` / `"ref"` /
- * `"api"`) so writers don't have to learn one canonical spelling
- * to get the right structured data. Anything else falls back to
- * `Article`, which is Google's "general docs page" assumption.
- */
-export function jsonLdTypeFor(pageType: string | undefined): string {
-  switch (pageType) {
-    case "tutorial":
-    case "how-to":
-    case "howto":
-      return "HowTo";
-    case "reference":
-    case "ref":
-    case "api":
-      return "TechArticle";
-    case "course":
-      return "Course";
-    default:
-      return "Article";
-  }
-}
-
-/**
- * Normalize the `customJsonLd` prop into an array. DocsLayout
- * accepts either a single object (most common case — one extra
- * Course / Organization block) or an array (sites that layer
- * several blocks per page).
- *
- * Returns an empty array for `undefined` so the template can
- * iterate uniformly without conditional rendering.
- */
-export function normalizeCustomJsonLd(
-  raw: Record<string, unknown> | Record<string, unknown>[] | undefined,
-): Record<string, unknown>[] {
-  if (!raw) return [];
-  if (Array.isArray(raw)) return raw;
-  return [raw];
-}
-
-export interface BuildArticleJsonLdOptions {
-  /** Already-resolved Schema.org `@type` (output of jsonLdTypeFor). */
-  type: string;
-  title: string;
-  /** Site name — used as the `provider` Organization for Course. */
-  siteName: string;
-  keywords: string[];
-  description?: string;
-  image?: string;
-  url?: string;
-  /**
-   * Page headings — used to synthesize `step[]` for HowTo. Each
-   * H2 (or H3 if no H2s exist) becomes a HowToStep with a deep
-   * link to the heading id.
-   */
-  headings?: ReadonlyArray<{ depth: number; slug: string; text: string }>;
-}
-
-/**
- * Build the JSON-LD payload for the page's primary structured-data
- * block, shaped per `@type`. The earlier implementation emitted
- * Article-shaped fields (`headline`) regardless of @type, which
- * meant HowTo / Course pages failed Google's Rich Results
- * requirements (HowTo needs `name` + `step`, Course needs `name` +
- * `description` + `provider`). See
- * `packages/cli/src/audit/rules/seo/json-ld-required-fields.ts`
- * for the validator that catches this.
- *
- * Schema.org's `name` is a Thing-level field accepted by every
- * @type, so we always emit it. `headline` is added on top for
- * Article-family types (Article, TechArticle) because Google's
- * Rich Results validator specifically requires it there. HowTo
- * gets a synthesized `step[]` from the page's H2 headings (each
- * H2 = one procedure step); Course gets a `provider` Organization
- * built from `siteName`.
- */
-export function buildArticleJsonLd(
-  opts: BuildArticleJsonLdOptions,
-): Record<string, unknown> {
-  const { type, title, siteName, keywords, description, image, url, headings } =
-    opts;
-
-  const block: Record<string, unknown> = {
-    "@context": "https://schema.org",
-    "@type": type,
-    name: title,
-  };
-  // Only when there are any. An empty `keywords: ""` asserts the page
-  // has no topics, which is a different claim from staying silent.
-  if (keywords.length > 0) block.keywords = keywords.join(", ");
-
-  if (type === "Article" || type === "TechArticle") {
-    block.headline = title;
-  }
-
-  if (description) block.description = description;
-  if (image) block.image = image;
-  if (url) block.url = url;
-
-  if (type === "HowTo") {
-    let stepHeadings = (headings ?? []).filter((h) => h.depth === 2);
-    if (stepHeadings.length === 0) {
-      stepHeadings = (headings ?? []).filter((h) => h.depth === 3);
-    }
-    block.step = stepHeadings.map((h) => ({
-      "@type": "HowToStep",
-      name: h.text,
-      url: url ? `${url}#${h.slug}` : `#${h.slug}`,
-    }));
-  }
-
-  if (type === "Course") {
-    block.provider = { "@type": "Organization", name: siteName };
-    if (!block.description) block.description = title;
-  }
-
-  return block;
-}
-
-/**
- * Identity structured data for a page that is not an article — a
- * homepage, a landing page, a section index.
- *
- * Exists because the article block is gated on `ogType === "article"`,
- * so those pages emitted NO structured data at all. An external agent
- * audit reported "No JSON-LD structured data found on homepage", which
- * was accurate: the one page most likely to be an agent's entry point
- * was the one describing itself the least.
- *
- * `WebSite` rather than `Organization` or `SoftwareApplication` on
- * purpose. Those are claims about what the site's OWNER is, and
- * guessing wrong is worse than saying less — a docs site for a product
- * is not itself the product. Owners wanting a stronger identity type
- * add it through `customJsonLd`, which layers on top of this.
- */
-export function buildWebSiteJsonLd(opts: {
-  siteName: string;
-  title: string;
-  description?: string;
-  url?: string;
-}): Record<string, unknown> {
-  const block: Record<string, unknown> = {
-    "@context": "https://schema.org",
-    "@type": "WebSite",
-    name: opts.siteName,
-  };
-  if (opts.title && opts.title !== opts.siteName) block.headline = opts.title;
-  if (opts.description) block.description = opts.description;
-  if (opts.url) block.url = opts.url;
-  return block;
-}
+export { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd, buildWebSiteJsonLd } from "@dogsbay/site-files";
+export type { BuildArticleJsonLdOptions } from "@dogsbay/site-files";

package/src/nav-filter.ts

@@ -29,6 +29,27 @@ export interface NavFilter {
   locale?: string;
   /** Current page's version segment (innermost, next to the page), if any. */
   version?: string;
+  /**
+   * The version served at the site root (`versions[].path: ""`): its pages
+   * have no version segment. When `version` is this one, the bucket is the
+   * namespace/locale prefix minus the other versions' folders
+   * (`versionSegments`) — the longest matching prefix wins.
+   */
+  rootVersion?: string;
+  /** The other versions' URL segments, left out of the root version's bucket. */
+  versionSegments?: string[];
+}
+
+/**
+ * The root-version fields of a `NavFilter`, from the switcherMap header
+ * (`versions[].root`). Empty when no version is served at the root.
+ */
+export function rootVersionFilter(
+  versions: Array<{ id: string; root?: boolean }> | undefined,
+): Pick<NavFilter, "rootVersion" | "versionSegments"> {
+  const root = versions?.find((v) => v.root)?.id;
+  if (!root) return {};
+  return { rootVersion: root, versionSegments: versions!.map((v) => v.id).filter((id) => id !== root) };
 }
 
 /**
@@ -40,26 +61,33 @@ export interface NavFilter {
 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(
+  const atRoot = filter.rootVersion !== undefined && filter.version === filter.rootVersion;
+  const segs = [filter.namespace, filter.locale, atRoot ? undefined : filter.version].filter(
     (s): s is string => s !== undefined && s !== "",
   );
-  if (segs.length === 0) return items;
+  // The root version's bucket leaves out the other versions' folders under its prefix.
+  const others = atRoot ? (filter.versionSegments ?? []).filter((v) => v && v !== filter.rootVersion) : [];
+  if (segs.length === 0 && others.length === 0) return items;
 
   const base = filter.basePath.replace(/\/$/, "");
-  const prefix = `${base}/${segs.join("/")}/`;
-  const prefixNoSlash = prefix.replace(/\/$/, "");
+  const prefix = `${base}/${segs.join("/")}${segs.length ? "/" : ""}`;
+  const prefixNoSlash = segs.length ? prefix.replace(/\/$/, "") : base || "/";
+  const excluded = others.map((v) => `${prefix}${v}`);
 
-  return items.flatMap((item) => filterOne(item, prefix, prefixNoSlash));
+  return items.flatMap((item) => filterOne(item, prefix, prefixNoSlash, excluded));
 }
 
-function filterOne(item: NavItem, prefix: string, prefixNoSlash: string): NavItem[] {
+function filterOne(item: NavItem, prefix: string, prefixNoSlash: string, excluded: string[]): NavItem[] {
   if (item.children && item.children.length > 0) {
-    const kept = item.children.flatMap((c) => filterOne(c, prefix, prefixNoSlash));
+    const kept = item.children.flatMap((c) => filterOne(c, prefix, prefixNoSlash, excluded));
     if (kept.length === 0) return [];
     return [{ ...item, children: kept }];
   }
   if (item.href !== undefined) {
-    return hrefMatchesPrefix(item.href, prefix, prefixNoSlash) ? [item] : [];
+    return hrefMatchesPrefix(item.href, prefix, prefixNoSlash) &&
+      !excluded.some((x) => hrefMatchesPrefix(item.href!, `${x}/`, x))
+      ? [item]
+      : [];
   }
   // Childless AND href-less: no navigation, no bucket membership. In a
   // filtered view it must be dropped.

package/src/pagefind-base-url.ts

@@ -0,0 +1,59 @@
+/**
+ * Pagefind result URLs, and the base they need.
+ *
+ * Pagefind stores each page's URL relative to the directory it indexed
+ * (`pagefind --site dist`), then prefixes every result with `baseUrl`. When
+ * the caller sets none, Pagefind derives it from where the bundle was loaded:
+ * the folder above `pagefind/`.
+ *
+ * That default is right for one of our two subpath layouts and wrong for the
+ * other, measured by decoding index fragments on live sites:
+ *
+ * | Deploy | Pages built into | Stored URL | Default base | Result |
+ * |---|---|---|---|---|
+ * | Workers subpath mount | `dist/<mount>/` (nested) | `/<mount>/page/` | `/<mount>/` | `/<mount>/<mount>/page/` — 404 |
+ * | GitHub Pages project | `dist/` (Astro `base`) | `/page/` | `/<repo>/` | `/<repo>/page/` — correct |
+ *
+ * So no single constant works: forcing `/` fixes the Workers mount and breaks
+ * every GitHub Pages project site. The emitter knows which layout it built and
+ * passes the base explicitly; this applies it.
+ */
+
+/** The slice of the Pagefind module this touches. */
+export interface PagefindOptionsModule {
+  options?: (opts: { baseUrl?: string }) => Promise<void> | void;
+}
+
+/**
+ * The base Pagefind should prefix results with: the served path that the
+ * INDEXED directory maps to.
+ *
+ * - Workers subpath mount — pages are built INTO `dist/<mount>/`, so the
+ *   index already carries the mount in every URL: `/`.
+ * - Anything else — pages sit at the `dist/` root and Astro's `base` (the
+ *   site.url path) is added at serve time, so that is the missing prefix:
+ *   `<urlBase>/`, or `/` at the host root.
+ *
+ * Note `basePath` (dogsbay's own prefix) is never part of it: pages are
+ * physically written under it, so the index already contains it.
+ */
+export function pagefindBaseUrl(urlBase: string, nestedOutDir: boolean): string {
+  if (nestedOutDir) return "/";
+  const base = urlBase.replace(/\/+$/, "");
+  return base ? `${base}/` : "/";
+}
+
+/**
+ * Apply an emitted base to a loaded Pagefind module. A missing base (a page
+ * emitted before the base was passed) leaves Pagefind's own default, so an
+ * un-rebuilt site behaves exactly as before rather than changing under it.
+ */
+export async function applyPagefindBaseUrl(
+  mod: PagefindOptionsModule,
+  baseUrl: string | undefined,
+): Promise<boolean> {
+  if (!baseUrl) return false;
+  if (typeof mod.options !== "function") return false;
+  await mod.options({ baseUrl });
+  return true;
+}

package/src/switcher.ts

@@ -20,6 +20,12 @@ export interface AxisEntry {
    */
   hidden?: boolean;
   default?: boolean;
+  /**
+   * Served at the site root (version axis only; `versions[].path: ""` on the
+   * default version): its pages have no version segment, so its landing
+   * page is `<basePath>/`, and its per-page URLs come from the variants.
+   */
+  root?: boolean;
 }
 
 export interface SwitcherVariant {
@@ -206,14 +212,16 @@ export function shouldRenderSwitcher(
 
 /**
  * Fallback URL for a row whose target variant doesn't exist —
- * lands on the axis's "landing page" (`<basePath>/<id>/`).
+ * lands on the axis's "landing page" (`<basePath>/<id>/`, or
+ * `<basePath>/` for the version served at the root).
  * Lets the switcher always be clickable even when a page is
  * untranslated for some axis combo.
  */
 export function fallbackLandingUrl(
   basePath: string,
   axisEntryId: string,
+  atRoot = false,
 ): string {
   const trimmed = basePath.replace(/\/$/, "");
-  return `${trimmed}/${axisEntryId}/`;
+  return atRoot ? `${trimmed}/` : `${trimmed}/${axisEntryId}/`;
 }

package/src/tag-list-data.ts

@@ -33,6 +33,29 @@ export interface BuildChipsOptions {
    * text. URL still uses the slug.
    */
   labels?: Record<string, string>;
+  /**
+   * Color chips whose prefix has no `color` with a palette color
+   * hashed from the first segment (`autoTagColor`). Default false.
+   */
+  autoColor?: boolean;
+}
+
+/** Palette order for automatic colors. */
+const AUTO_PALETTE: readonly TagPaletteName[] = ["blue", "amber", "emerald", "violet", "rose", "slate"];
+
+/**
+ * A stable palette color for a tag segment: FNV-1a hash of the
+ * lowercased segment, modulo the palette. The same segment gets the
+ * same color on every page and every build; with more distinct tags
+ * than colors, colors repeat.
+ */
+export function autoTagColor(segment: string): TagPaletteName {
+  let hash = 0x811c9dc5;
+  for (const ch of segment.toLowerCase()) {
+    hash ^= ch.codePointAt(0)!;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return AUTO_PALETTE[hash % AUTO_PALETTE.length];
 }
 
 export interface ChipModel {
@@ -164,7 +187,7 @@ export function buildChips(
   options: BuildChipsOptions,
 ): ChipModel[] {
   const safe = filterTags(tags);
-  const { indexPath, prefixes, labels } = options;
+  const { indexPath, prefixes, labels, autoColor = false } = options;
 
   return safe.map((tag): ChipModel => {
     const href = `${indexPath}/${tag}/`;
@@ -182,7 +205,7 @@ export function buildChips(
         href,
         prefixLabel: null,
         leafLabel: overrideLeaf ?? tag,
-        color: null,
+        color: autoColor ? autoTagColor(firstSegment) : null,
       };
     }
 
@@ -196,7 +219,7 @@ export function buildChips(
       href,
       prefixLabel: prefixEntry.label ?? null,
       leafLabel: leafLabel.length > 0 ? leafLabel : tag,
-      color: prefixEntry.color ?? null,
+      color: prefixEntry.color ?? (autoColor ? autoTagColor(firstSegment) : null),
     };
   });
 }

package/src/version-redirect.ts

@@ -31,6 +31,15 @@ export interface AxisRedirectConfig {
   defaultVersion?: string;
   /** Full set of declared version ids. Empty/undefined → axis inactive. */
   knownVersions?: string[];
+  /**
+   * The version served at the site root (`versions[].path: ""`, the
+   * default version). A URL with no version segment is one of its pages,
+   * so the version is never injected; a URL starting with another known
+   * version's segment is that version's (the longest matching prefix
+   * wins). Only the locale redirect remains. format-astro emits no version
+   * config at all in that case; this keeps the helper right when given one.
+   */
+  rootVersion?: string;
   /** Default locale id; required when locale axis is active. */
   defaultLocale?: string;
   /** Full set of declared locale ids. Empty/undefined → axis inactive. */
@@ -126,7 +135,8 @@ export function shouldRedirectToDefaultVersion(
   if (
     versionAxisActive &&
     cursor < segments.length &&
-    knownVersions.has(segments[cursor])
+    knownVersions.has(segments[cursor]) &&
+    segments[cursor] !== config.rootVersion
   ) {
     presentVersion = segments[cursor];
     cursor += 1;
@@ -134,13 +144,16 @@ export function shouldRedirectToDefaultVersion(
 
   // What's the rest of the path beyond the recognised axis prefixes?
   const tailSegments = segments.slice(cursor);
+  // With a root version, a URL without a version segment is already complete.
+  const versionMissing =
+    versionAxisActive && presentVersion === undefined && !config.rootVersion;
   if (tailSegments.length === 0) {
     // The path is JUST a known axis prefix (e.g. /docs/en/ or
     // /docs/v1/). Treat as the axis's landing page; no redirect
     // needed unless other axes are MISSING from the URL too.
     if (
       (localeAxisActive && presentLocale === undefined) ||
-      (versionAxisActive && presentVersion === undefined)
+      versionMissing
     ) {
       // Some axis still missing — fall through to redirect.
     } else {
@@ -150,7 +163,7 @@ export function shouldRedirectToDefaultVersion(
 
   // If all required-active axes are present, no redirect needed.
   const localeNeeded = localeAxisActive && presentLocale === undefined;
-  const versionNeeded = versionAxisActive && presentVersion === undefined;
+  const versionNeeded = versionMissing;
   if (!localeNeeded && !versionNeeded) return null;
 
   // Compose the redirect target with missing segments injected
@@ -159,7 +172,7 @@ export function shouldRedirectToDefaultVersion(
   if (localeAxisActive) {
     out.push(presentLocale ?? config.defaultLocale!);
   }
-  if (versionAxisActive) {
+  if (versionAxisActive && (presentVersion !== undefined || !config.rootVersion)) {
     out.push(presentVersion ?? config.defaultVersion!);
   }
   out.push(...tailSegments);