npm - @dogsbay/docs-layout - Versions diffs - 0.2.0-beta.7 → 0.2.0-beta.72 - Mend

@dogsbay/docs-layout 0.2.0-beta.7 → 0.2.0-beta.72

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/package.json CHANGED Viewed

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

package/src/DocsLayout.astro CHANGED Viewed

@@ -31,6 +31,7 @@ import SidebarMenuItem from "@dogsbay/ui/sidebar/SidebarMenuItem.astro";
 import SidebarMenuButton from "@dogsbay/ui/sidebar/SidebarMenuButton.astro";
 import SidebarSeparator from "@dogsbay/ui/sidebar/SidebarSeparator.astro";
 import SidebarNavTree from "@dogsbay/ui/sidebar/SidebarNavTree.astro";
+import DocsNavClient from "./DocsNavClient.astro";
 import Separator from "@dogsbay/ui/separator/Separator.astro";
 import ThemeToggle from "@dogsbay/ui/theme-toggle/ThemeToggle.astro";
 import DocsToc from "./DocsToc.astro";
@@ -44,7 +45,7 @@ import VersionSwitcher from "./VersionSwitcher.astro";
 import LocaleSwitcher from "./LocaleSwitcher.astro";
 import { filterNavByAxis } from "./nav-filter.js";
 import type { LlmProviderName } from "./llm-actions.js";
-import { jsonLdTypeFor, normalizeCustomJsonLd } from "./json-ld.js";
+import { jsonLdTypeFor, normalizeCustomJsonLd, buildArticleJsonLd } from "./json-ld.js";
 import { resolveTagKeywords } from "./tag-list-data.js";
 interface NavItem {
@@ -112,7 +113,13 @@ interface Props {
   siteDescription?: string;
   /** Copyright text (HTML allowed) */
   copyright?: string;
-  /** Favicon path (default: "/favicon.ico"). Set to false to disable. */
+  /**
+   * Favicon path. No host-root default — that 404s on subpath
+   * deploys. The format-astro emitter passes a combined-prefix
+   * path (e.g. `/<repo>/favicon.ico`) computed from site.url +
+   * basePath. Pass an empty string or `false` to disable. When
+   * undefined, no `<link rel="icon">` is emitted.
+   */
   favicon?: string | false;
   /** Per-page OG image URL. Overrides defaultOgImage. */
   ogImage?: string;
@@ -127,16 +134,25 @@ interface Props {
   /** Theme color hint for browsers (hex string) */
   themeColor?: string;
   /**
-   * Emit `<meta name="robots" content="noindex, nofollow">` when
+   * Emit `noindex` in the `<meta name="robots">` directive when
    * true. Tells external search engines (Google, Bing) to skip
-   * this page. Has NO effect on in-site Pagefind search — for
-   * that, use `excludeFromSearch`. The two are independent: a
-   * page can be excluded from external SEs but still appear in
-   * Pagefind (e.g. duplicate / old content readers might still
-   * want to find when they're already on the site), or vice
-   * versa.
+   * indexing this page. Independent of `nofollow` — common pattern
+   * for tag / index pages is noindex + follow (don't list this
+   * page in results, but do crawl through to the real content).
+   *
+   * Has NO effect on in-site Pagefind search — for that, use
+   * `excludeFromSearch`. The two are independent: a page can be
+   * excluded from external SEs but still appear in Pagefind (e.g.
+   * duplicate / old content readers might still want to find when
+   * they're already on the site), or vice versa.
    */
   noindex?: boolean;
+  /**
+   * Emit `nofollow` in the `<meta name="robots">` directive when
+   * true. Tells crawlers not to follow outbound links from this
+   * page. Independent of `noindex`. Default false.
+   */
+  nofollow?: boolean;
   /**
    * Exclude this page from in-site Pagefind search results.
    *
@@ -256,6 +272,23 @@ interface Props {
    * elements in `<body>`.
    */
   category?: string[];
+  /**
+   * Custom-taxonomy values from `meta.taxonomies` — anything declared
+   * in `taxonomies:` config that isn't one of the five hardcoded
+   * built-ins (`tags`, `category`, `audience`, `type`, `status`).
+   *
+   * Each entry becomes one `<div data-pagefind-filter="<name>:<value>">`
+   * inside the indexed body, so the search dialog grows a checkbox
+   * group for every custom taxonomy automatically. No extra config
+   * needed beyond declaring the taxonomy in `dogsbay.config.yml` —
+   * the search dialog discovers facets at index time and renders
+   * whatever Pagefind reports.
+   *
+   * Display labels for the checkboxes flow through
+   * `taxonomyDisplay[<name>]` (same prefix/label config that drives
+   * chip rendering elsewhere). When unset, raw slugs are shown.
+   */
+  taxonomies?: Record<string, string[]>;
   /**
    * Map of taxonomy name → index path for declared taxonomies.
    * Used to wire links from built-in field badges (TypeBadge,
@@ -324,6 +357,19 @@ interface Props {
    * (`<basePath>/<version>/`). Defaults to "/docs".
    */
   basePath?: string;
+  /**
+   * Sidebar navigation render mode.
+   *
+   * - `"client"` (default): emit the small `<DocsNavClient />` placeholder;
+   *   the tree is hydrated from `/_dogsbay/nav.json` once per session.
+   *   Page HTML shrinks dramatically at scale (~50 KB vs ~1.2 MB on a
+   *   2k-page site). No-JS users see a sitemap fallback link.
+   * - `"ssr-full"`: render the full nav tree into every page's HTML.
+   *   Best for very small sites or strict no-JS / SEO contexts.
+   *
+   * See plans/client-rendered-nav.md.
+   */
+  navMode?: "client" | "ssr-full";
   /**
    * Per-page LLM action UI. When set and `enabled !== false`, renders
    * the PageActions cluster (Copy markdown + Open in Claude/ChatGPT/
@@ -376,7 +422,7 @@ const {
   editUrl,
   lastUpdated,
   copyright,
-  favicon = "/favicon.ico",
+  favicon,
   ogImage,
   defaultOgImage,
   ogType = "article",
@@ -384,11 +430,18 @@ const {
   twitterHandle,
   themeColor,
   noindex,
+  nofollow,
   excludeFromSearch,
   plausibleDomain,
   plausibleScriptUrl,
   hideSearch = false,
-  pagefindUrl = "/pagefind/",
+  // No default for pagefindUrl — host-root absolute paths break on
+  // subpath-mounted deploys (GH Pages project pages, multi-mount
+  // Cloudflare). format-astro's emitter always passes the
+  // combined-prefix-aware URL; manual instantiation must too.
+  // Undefined here propagates to SearchDialog where the JS loader
+  // throws on first open instead of silently 404'ing the bundle.
+  pagefindUrl,
   mdMirror = false,
   tags,
   tagsIndexPath = "/tags",
@@ -398,6 +451,7 @@ const {
   pageType,
   audience,
   category,
+  taxonomies,
   taxonomyIndexPaths,
   taxonomyDisplay,
   autoH1,
@@ -407,6 +461,7 @@ const {
   multiSource,
   switcherMap,
   basePath,
+  navMode = "client",
   wideLayout = false,
   class: className,
 } = Astro.props;
@@ -428,6 +483,16 @@ const showLlmActionsInline =
   llmActionsEnabled
   && (llmActionsPlacement === "inline" || llmActionsPlacement === "both");
 const llmFooterLink = !!llmActions && llmActions.footerLink !== false;
+// Per-mount llms.txt URL — Dogsbay emits `<basePath>/llms.txt`
+// (sitemap-index pattern), so the footer link must be basePath-
+// prefixed too. Falls back to `/llms.txt` when basePath is empty
+// or unset, matching the platform's host-root single-site case.
+const llmsLinkHrefResolved = (() => {
+  const bp = (basePath ?? "").replace(/\/+$/, "");
+  if (!bp) return "/llms.txt";
+  const prefix = bp.startsWith("/") ? bp : `/${bp}`;
+  return `${prefix}/llms.txt`;
+})();
 // Compute href targets for the type / status badges. A field is
 // linkable only when (a) the user declared a `taxonomies.<field>`
@@ -453,9 +518,25 @@ const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
 const metaDescription = description ?? siteDescription;
 const metaOgImage = ogImage ?? defaultOgImage;
 const isAbsoluteSiteUrl = /^https?:\/\//.test(siteUrl);
+// Compose canonical from ORIGIN + pathname. siteUrl may carry a
+// path component (the urlBase that drives Astro's `base` — see
+// plans/astro-base-from-site-url.md), and Astro.url.pathname
+// already includes that prefix. Naively concatenating siteUrl +
+// pathname double-counts the urlBase (e.g. .../repo/repo/page).
+// Strip path off siteUrl by reparsing as a URL.
+let canonicalOrigin: string | undefined;
+if (isAbsoluteSiteUrl) {
+  try {
+    const u = new URL(siteUrl);
+    canonicalOrigin = `${u.protocol}//${u.host}`;
+  } catch {
+    // Malformed siteUrl — fall back to the original (no path) behavior.
+    canonicalOrigin = siteUrl.replace(/\/$/, "");
+  }
+}
 const computedCanonical = canonicalUrl
-  ?? (isAbsoluteSiteUrl
-    ? siteUrl.replace(/\/$/, "") + Astro.url.pathname
+  ?? (canonicalOrigin
+    ? canonicalOrigin + Astro.url.pathname
     : undefined);
 // Markdown mirror — append `.md` to the current path for the alternate link
@@ -482,15 +563,16 @@ const tagKeywords = resolveTagKeywords(tags, tagLabels);
 // search engines key off for educational / tutorial / reference
 // SERP rendering. See `json-ld.ts` for the full mapping table.
 const articleJsonLd = (ogType === "article" && tagKeywords.length > 0)
-  ? {
-      "@context": "https://schema.org",
-      "@type": jsonLdTypeFor(pageType),
-      headline: title,
-      keywords: tagKeywords.join(", "),
-      ...(metaDescription ? { description: metaDescription } : {}),
-      ...(metaOgImage ? { image: metaOgImage } : {}),
-      ...(computedCanonical ? { url: computedCanonical } : {}),
-    }
+  ? buildArticleJsonLd({
+      type: jsonLdTypeFor(pageType),
+      title,
+      siteName,
+      keywords: tagKeywords,
+      description: metaDescription,
+      image: metaOgImage,
+      url: computedCanonical,
+      headings,
+    })
   : undefined;
 // `customJsonLd` accepts either a single object or an array.
@@ -510,11 +592,22 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     <title>{title} | {siteName}</title>
     {metaDescription && <meta name="description" content={metaDescription} />}
-    {favicon !== false && <link rel="icon" href={favicon} />}
+    {favicon && <link rel="icon" href={favicon} />}
     {themeColor && <meta name="theme-color" content={themeColor} />}
     {/* External search engine directive — orthogonal to in-site
-       Pagefind exclusion. */}
-    {noindex && <meta name="robots" content="noindex, nofollow" />}
+       Pagefind exclusion. `noindex` + `nofollow` are independent
+       bits per the meta-robots spec; emit only the directives that
+       are set. Combining them when both are set keeps the tag
+       compact (`<meta name="robots" content="noindex, nofollow">`)
+       instead of emitting two tags. */}
+    {(noindex || nofollow) && (
+      <meta
+        name="robots"
+        content={[noindex && "noindex", nofollow && "nofollow"]
+          .filter(Boolean)
+          .join(", ")}
+      />
+    )}
     {/* In-site Pagefind exclusion is wired via two coordinated
        attributes on <body> and <main> below — see the prop docs
@@ -529,6 +622,12 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
     {computedCanonical && <link rel="canonical" href={computedCanonical} />}
     {mdMirrorHref && <link rel="alternate" type="text/markdown" href={mdMirrorHref} />}
+    {/* Programmatic llms.txt discovery — agents that follow head
+       link rels get the per-mount llms.txt without parsing HTML.
+       Mirrors the existing _headers Link rel="describedby" used by
+       Cloudflare Pages / Workers. */}
+    <link rel="alternate" type="text/plain" title="llms.txt" href={llmsLinkHrefResolved} />
+    <link rel="describedby" type="text/plain" href={llmsLinkHrefResolved} />
     {/* Open Graph */}
     <meta property="og:type" content={ogType} />
@@ -592,7 +691,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarHeader>
           <SidebarMenu>
             <SidebarMenuItem>
-              <SidebarMenuButton size="lg" href={siteUrl} isActive={currentPath === siteUrl || currentPath === "/"}>
+              <SidebarMenuButton size="lg" href={basePath || "/"} isActive={currentPath === basePath || currentPath === "/"}>
                 <div class="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
                   <Fragment set:html={siteIcon} />
                 </div>
@@ -608,7 +707,24 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
         <SidebarSeparator />
         <SidebarContent>
-          {navGroups ? (
+          {navMode === "client" ? (
+            // Client-render mode: emit one DocsNavClient placeholder
+            // inside a single SidebarGroup, regardless of navGroups.
+            // The group-label shape doesn't apply when the tree is
+            // hydrated by JS — multi-group nav is reconstructed
+            // client-side from the same /_dogsbay/nav.json shape.
+            // See plans/client-rendered-nav.md.
+            <SidebarGroup>
+              <SidebarGroupContent>
+                <DocsNavClient
+                  currentPath={currentPath}
+                  basePath={basePath ?? ""}
+                  version={multiSource?.version}
+                  locale={multiSource?.locale}
+                />
+              </SidebarGroupContent>
+            </SidebarGroup>
+          ) : navGroups ? (
             navGroups.map(group => (
               <SidebarGroup>
                 <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
@@ -709,9 +825,30 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
               the actual page content. Filter elements live in here
               now to stay inside that scope.
             */}
-            {Array.isArray(tags) && tags.map((tag) => (
-              <div hidden data-pagefind-filter={`tag:${tag}`}></div>
-            ))}
+            {/*
+              Slash-nested tags whose prefix is declared in
+              `taxonomies.tags.prefixes` emit as per-prefix filter
+              divs so each prefix becomes its own Pagefind facet
+              column (Difficulty, Topic, Persona, …) instead of
+              pooling under a single "Tag" column.
+              Plain tags and tags whose prefix isn't declared fall
+              back to the pooled `tag:` filter — backward-compatible
+              for sites that haven't declared prefixes.
+              See plans/per-prefix-search-facets.md.
+            */}
+            {Array.isArray(tags) && tags.map((tag) => {
+              const slash = tag.indexOf("/");
+              if (slash > 0) {
+                const prefix = tag.slice(0, slash);
+                const leaf = tag.slice(slash + 1);
+                if (tagPrefixes && tagPrefixes[prefix]) {
+                  return <div hidden data-pagefind-filter={`${prefix}:${leaf}`}></div>;
+                }
+              }
+              return <div hidden data-pagefind-filter={`tag:${tag}`}></div>;
+            })}
             {Array.isArray(audience) && audience.map((value) => (
               <div hidden data-pagefind-filter={`audience:${value}`}></div>
             ))}
@@ -720,6 +857,20 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             ))}
             {status && <div hidden data-pagefind-filter={`status:${status}`}></div>}
             {pageType && <div hidden data-pagefind-filter={`type:${pageType}`}></div>}
+            {/*
+              Custom-taxonomy filters. Any taxonomy declared in
+              `dogsbay.config.yml` that isn't one of the five built-ins
+              flows through here, so `difficulty: intermediate` (etc.)
+              becomes a real Pagefind facet checkbox automatically.
+              See plans/beta-launch-followups.md for context.
+            */}
+            {taxonomies && Object.entries(taxonomies).flatMap(([name, values]) =>
+              Array.isArray(values)
+                ? values.map((value) => (
+                    <div hidden data-pagefind-filter={`${name}:${value}`}></div>
+                  ))
+                : []
+            )}
             <div class:list={["mx-auto", wideLayout ? "max-w-7xl" : "max-w-3xl"]}>
               {/*
@@ -802,6 +953,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
                 next={next}
                 copyright={copyright}
                 llmsLink={llmFooterLink}
+                llmsLinkHref={llmsLinkHrefResolved}
               />
             </div>
           </main>

package/src/DocsNavClient.astro ADDED Viewed

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

package/src/SearchDialog.astro CHANGED Viewed

@@ -28,8 +28,13 @@ import type { TaxonomyDisplay } from "@dogsbay/types";
 interface Props {
   /**
-   * Path prefix where Pagefind's index lives. Default: "/pagefind/".
-   * Override when a site uses a non-root base path (e.g. "/docs/pagefind/").
+   * Path where Pagefind's index lives, e.g. `/pagefind/` or
+   * `/<repo>/pagefind/` for subpath-mounted deploys. NO DEFAULT —
+   * a host-root default would silently 404 on subpath deploys
+   * (GH Pages project pages, multi-mount Cloudflare). The
+   * format-astro emitter passes the combined-prefix-aware URL;
+   * manual instantiations must do the same. When undefined, the
+   * search dialog throws on first open with a clear console error.
    */
   pagefindUrl?: string;
   /** Placeholder text for the search input */
@@ -44,7 +49,7 @@ interface Props {
 }
 const {
-  pagefindUrl = "/pagefind/",
+  pagefindUrl,
   placeholder = "Search docs...",
   taxonomyDisplay,
 } = Astro.props;
@@ -156,6 +161,7 @@ const {
     shapeFacets,
     resolveFacetLabel,
     resolveFacetTitle,
+    sortFacetNames,
     filterStateToUrlParams,
     parseFiltersFromUrl,
     filterStateToPagefindFilters,
@@ -177,10 +183,15 @@ const {
     meta: { title?: string };
     sub_results?: Array<{ title: string; url: string; excerpt: string }>;
   };
+  // Filter values match what filterStateToPagefindFilters emits:
+  // each facet wrapped in `{any: [...]}` for OR-within-facet semantics.
+  // Pagefind also accepts other operator shapes (`all`/`none`/`not`,
+  // bare strings, bare arrays) but we only emit the `any` form.
+  type PagefindFilterValue = { any: string[] };
   type PagefindModule = {
     search(
       query: string,
-      options?: { filters?: Record<string, string[]> },
+      options?: { filters?: Record<string, PagefindFilterValue> },
     ): Promise<{ results: PagefindResult[] }>;
     filters(): Promise<Record<string, Record<string, number>>>;
   };
@@ -218,7 +229,22 @@ const {
     async function ensurePagefindLoaded() {
       if (pagefind) return;
       if (loadingPagefind) return loadingPagefind;
-      const url = (dialog!.dataset.pagefindUrl ?? "/pagefind/") + "pagefind.js";
+      // pagefindUrl is required — a "/pagefind/" fallback would
+      // silently 404 on subpath-mounted deploys (GH Pages project
+      // pages, multi-mount Cloudflare). The emitter always passes
+      // a combined-prefix-aware value via data-pagefind-url. If it's
+      // missing the page wasn't built through format-astro and the
+      // caller forgot to pass it.
+      const dataUrl = dialog!.dataset.pagefindUrl;
+      if (!dataUrl) {
+        console.error(
+          "[dogsbay] SearchDialog: pagefindUrl prop missing. " +
+          "Pass the combined-prefix path (e.g. '/<base>/pagefind/') " +
+          "from your DocsLayout instantiation.",
+        );
+        return;
+      }
+      const url = dataUrl + "pagefind.js";
       loadingPagefind = (async () => {
         try {
           const mod = (await import(/* @vite-ignore */ url)) as PagefindModule;
@@ -320,7 +346,10 @@ const {
      * filters, the sidebar stays hidden — single-column layout.
      */
     function renderFacets() {
-      const facetNames = Object.keys(availableFacets);
+      const facetNames = sortFacetNames(
+        Object.keys(availableFacets),
+        taxonomyDisplay,
+      );
       if (facetNames.length === 0) {
         facetsBox!.classList.add("hidden");
         return;

package/src/TaxonomyTerm.astro CHANGED Viewed

@@ -93,15 +93,22 @@ function segmentLabel(depth: number): string {
 const titleSegments = term.fullPath.map((_, i) => segmentLabel(i));
-// Breadcrumb segments — clickable parent paths.
+// Breadcrumb segments — only link to prefixes that have their own
+// term page. When a taxonomy is non-hierarchical, only full-path
+// terms exist in `data.terms`; linking to `/tags/<prefix>/` for an
+// intermediate segment would 404. Render those as plain text instead.
 function breadcrumbs() {
-  const out: { label: string; href: string }[] = [
+  const termKeys = new Set(data.terms.map((t) => t.fullPath.join("/")));
+  const out: { label: string; href?: string }[] = [
     { label: displayName, href: `${data.indexPath}/` },
   ];
   for (let i = 0; i < term.fullPath.length - 1; i++) {
+    const prefix = term.fullPath.slice(0, i + 1).join("/");
     out.push({
       label: segmentLabel(i),
-      href: `${data.indexPath}/${term.fullPath.slice(0, i + 1).join("/")}/`,
+      href: termKeys.has(prefix)
+        ? `${data.indexPath}/${prefix}/`
+        : undefined,
     });
   }
   return out;
@@ -120,7 +127,11 @@ const crumbs = breadcrumbs();
   <nav class="mb-3 text-sm text-muted-foreground" aria-label="Breadcrumbs">
     {crumbs.map((c, i) => (
       <span>
-        <a href={c.href} class="hover:text-foreground hover:underline">{c.label}</a>
+        {c.href ? (
+          <a href={c.href} class="hover:text-foreground hover:underline">{c.label}</a>
+        ) : (
+          <span>{c.label}</span>
+        )}
         {i < crumbs.length - 1 && <span class="mx-1.5">/</span>}
       </span>
     ))}

package/src/docs-nav-client.ts ADDED Viewed

@@ -0,0 +1,265 @@
+/**
+ * Client-side sidebar nav hydration.
+ *
+ * Fetches `/_dogsbay/nav.json` once per session, renders the tree DOM
+ * to mirror `@dogsbay/ui/sidebar/SidebarNavTree.astro`'s structure,
+ * and re-highlights the current page on each Astro view-transition
+ * page-load.
+ *
+ * Design constraints:
+ *   - DOM output matches SidebarNavTree exactly (same tags, classes,
+ *     data-attributes) so Tailwind's compiled CSS styles us correctly
+ *     and any sidebar-system selectors (e.g. `data-sidebar="nav-tree"`
+ *     hooks) keep working.
+ *   - Filter by `version` / `locale` matches `nav-filter.ts`'s SSR
+ *     filter so a multi-axis site renders the same nav as `ssr-full`
+ *     mode (without the multiplicative HTML cost).
+ *   - One fetch per session. The `nav.json` URL is served with
+ *     `Cache-Control: immutable` by Astro's static build (it lives
+ *     under `public/_dogsbay/`), so the browser cache holds it across
+ *     navigations.
+ *
+ * See plans/client-rendered-nav.md.
+ */
+import { filterNavByAxis } from "./nav-filter.js";
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+/**
+ * Module-level cache so multiple page loads in the same SPA session
+ * share the same fetched nav data. Cleared by re-loads (full page
+ * navigations) but Astro's view transitions re-execute the script
+ * module without reloading the page — so on view-transition the
+ * cached promise is reused and no extra fetch fires.
+ */
+let navPromise: Promise<NavItem[]> | null = null;
+function fetchNav(url: string): Promise<NavItem[]> {
+  if (!navPromise) {
+    navPromise = fetch(url, { credentials: "same-origin" }).then((r) => {
+      if (!r.ok) throw new Error(`nav.json fetch failed: ${r.status}`);
+      return r.json() as Promise<NavItem[]>;
+    });
+  }
+  return navPromise;
+}
+function normalize(path: string): string {
+  return path.replace(/\/$/, "") || "/";
+}
+function hasActiveDescendant(item: NavItem, current: string): boolean {
+  if (item.href && normalize(item.href) === current) return true;
+  return item.children?.some((c) => hasActiveDescendant(c, current)) ?? false;
+}
+/**
+ * Render a single nav item into a `<li>` DOM node. Matches
+ * SidebarNavTree's per-level class set exactly so styling stays in
+ * sync. Padding is computed from `level` the same way (`8 + level*12`
+ * pixels) so indentation lines up across the same render.
+ */
+function renderItem(item: NavItem, current: string, level: number): HTMLLIElement {
+  const li = document.createElement("li");
+  li.dataset.sidebar = "nav-tree-item";
+  const active = item.href ? normalize(item.href) === current : false;
+  const hasChildren = !!item.children && item.children.length > 0;
+  const padLeft = `${8 + level * 12}px`;
+  const heightClass = level === 0 ? "h-8" : "h-7";
+  if (hasChildren) {
+    const details = document.createElement("details");
+    if (active || hasActiveDescendant(item, current)) details.open = true;
+    const summary = document.createElement("summary");
+    summary.className = [
+      "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    summary.style.paddingLeft = padLeft;
+    if (item.href) summary.dataset.navHref = item.href;
+    if (active) summary.dataset.active = "true";
+    // Chevron SVG — matches SidebarNavTree's rotation-on-open via CSS
+    // (`details[open] > summary [data-chevron] { transform: rotate(90deg); }`).
+    summary.innerHTML =
+      '<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" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>';
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      summary.appendChild(iconSpan);
+    }
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    summary.appendChild(label);
+    details.appendChild(summary);
+    // Recurse — nested `<ul>` mirrors SidebarNavTree's `<Astro.self>`.
+    const childUl = document.createElement("ul");
+    childUl.className = "flex min-w-0 flex-col";
+    childUl.dataset.sidebar = "nav-tree";
+    childUl.dataset.level = String(level + 1);
+    for (const child of item.children!) {
+      childUl.appendChild(renderItem(child, current, level + 1));
+    }
+    details.appendChild(childUl);
+    li.appendChild(details);
+  } else {
+    const a = document.createElement("a");
+    a.href = item.href || "#";
+    a.className = [
+      "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2",
+      heightClass,
+      active ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    a.style.paddingLeft = padLeft;
+    if (active) a.dataset.active = "true";
+    if (item.href) a.dataset.navHref = item.href;
+    // Spacer to align leaf text with branch text (which has a chevron).
+    const spacer = document.createElement("span");
+    spacer.className = "size-4 shrink-0";
+    a.appendChild(spacer);
+    if (item.icon) {
+      const iconSpan = document.createElement("span");
+      iconSpan.className = "shrink-0 [&>svg]:size-4";
+      iconSpan.innerHTML = item.icon;
+      a.appendChild(iconSpan);
+    }
+    const label = document.createElement("span");
+    label.className = "truncate";
+    label.textContent = item.label;
+    a.appendChild(label);
+    li.appendChild(a);
+  }
+  return li;
+}
+function renderTree(items: NavItem[], current: string, root: HTMLElement): void {
+  const ul = document.createElement("ul");
+  ul.className =
+    "flex min-w-0 flex-col w-full group-data-[collapsible=icon]:hidden";
+  ul.dataset.sidebar = "nav-tree";
+  ul.dataset.level = "0";
+  for (const item of items) {
+    ul.appendChild(renderItem(item, current, 0));
+  }
+  // Replace skeleton in one DOM op so there's no flash of partial state.
+  root.replaceChildren(ul);
+  root.removeAttribute("aria-busy");
+}
+/**
+ * Re-highlight the active item without rebuilding the whole tree.
+ * Used on `astro:page-load` when view transitions land on a new
+ * route — we re-toggle the `data-active` attribute and re-apply the
+ * active classes, then expand the new active branch's ancestors.
+ *
+ * Cheaper than a full re-render (no fetch, no DOM rebuild). For
+ * the wider hydration loop we still re-render when a brand-new nav
+ * structure is needed (e.g. switching versions), but path-only
+ * navigation just re-highlights.
+ */
+function rehighlight(root: HTMLElement, current: string): void {
+  const ACTIVE_CLASSES = [
+    "bg-sidebar-accent",
+    "font-medium",
+    "text-sidebar-accent-foreground",
+  ];
+  const items = root.querySelectorAll<HTMLElement>("[data-nav-href]");
+  for (const el of Array.from(items)) {
+    const href = el.dataset.navHref;
+    const active = !!href && normalize(href) === current;
+    if (active) {
+      el.dataset.active = "true";
+      el.classList.add(...ACTIVE_CLASSES);
+    } else {
+      delete el.dataset.active;
+      el.classList.remove(...ACTIVE_CLASSES);
+    }
+  }
+  // Expand ancestors of the new active item.
+  const active = root.querySelector<HTMLElement>('[data-active="true"]');
+  if (active) {
+    let parent: HTMLElement | null = active.parentElement;
+    while (parent) {
+      if (parent.tagName === "DETAILS") {
+        (parent as HTMLDetailsElement).open = true;
+      }
+      parent = parent.parentElement;
+    }
+  }
+}
+/**
+ * Public entry point. Called once from `<DocsNavClient />`'s inline
+ * script tag. Idempotent — subsequent calls (e.g. from view
+ * transitions) are no-ops once the tree has been rendered; they just
+ * re-highlight against the new pathname.
+ */
+export async function hydrateDocsNav(): Promise<void> {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  const navUrl = root.dataset.navUrl;
+  if (!navUrl) {
+    console.warn("docs-nav: missing data-nav-url");
+    return;
+  }
+  const current = normalize(root.dataset.currentPath || location.pathname);
+  const basePath = root.dataset.basePath || "";
+  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",
+      version: version || undefined,
+      locale: locale || undefined,
+    });
+    renderTree(filtered, current, root);
+  } catch (err) {
+    console.error("docs-nav: hydration failed", err);
+    root.setAttribute("aria-busy", "false");
+    // Keep skeleton so layout doesn't collapse on failure; a real
+    // user will reload or follow the noscript link.
+  }
+}
+// Re-run on view transitions. astro:page-load fires both on initial
+// load and after each ClientRouter transition; the module-level
+// `navPromise` cache makes the post-transition path a fast
+// highlight-only pass without re-fetching.
+document.addEventListener("astro:page-load", () => {
+  const root = document.getElementById("docs-nav-root");
+  if (!root) return;
+  // If tree is already rendered (no aria-busy), just re-highlight.
+  if (root.getAttribute("aria-busy") === null) {
+    const current = normalize(root.dataset.currentPath || location.pathname);
+    rehighlight(root, current);
+  } else {
+    void hydrateDocsNav();
+  }
+});

package/src/json-ld.ts CHANGED Viewed

@@ -53,3 +53,80 @@ export function normalizeCustomJsonLd(
   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,
+    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;
+}

package/src/search-facets.ts CHANGED Viewed

@@ -16,6 +16,13 @@ import type { PrefixDisplay } from "./tag-list-data.js";
 export interface TaxonomyDisplay {
   prefixes?: Record<string, PrefixDisplay>;
   labels?: Record<string, string>;
+  /**
+   * Sort weight for the facet column in the search dialog. Lower
+   * numbers appear first. Facets without an `order` sort
+   * alphabetically *after* any pinned ones — so `{ type: { order: 1 } }`
+   * promotes "Type" to the top while everything else stays alpha.
+   */
+  order?: number;
 }
 /** Map of taxonomy name → display config. */
@@ -120,6 +127,40 @@ export function resolveFacetTitle(facetName: string): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
+/**
+ * Return facet names in sidebar render order.
+ *
+ * Pagefind's `filters()` map iterates in index-discovery order
+ * (effectively the first page Pagefind happened to read), so without
+ * sorting the column order is arbitrary and shifts between builds.
+ * Order rule:
+ *  1. Facets with a numeric `order` in their `TaxonomyDisplay`
+ *     come first, ascending — use this to pin "Type" or "Audience"
+ *     to the top regardless of name.
+ *  2. Everything else sorts alphabetically by facet name.
+ * Stable within each tier so ties don't shuffle.
+ */
+export function sortFacetNames(
+  names: string[],
+  display?: TaxonomyDisplayMap,
+): string[] {
+  const withOrder = (name: string): number | undefined => {
+    const o = display?.[name]?.order;
+    return typeof o === "number" ? o : undefined;
+  };
+  return [...names].sort((a, b) => {
+    const oa = withOrder(a);
+    const ob = withOrder(b);
+    if (oa !== undefined && ob !== undefined) {
+      if (oa !== ob) return oa - ob;
+      return a.localeCompare(b);
+    }
+    if (oa !== undefined) return -1;
+    if (ob !== undefined) return 1;
+    return a.localeCompare(b);
+  });
+}
 // ── URL persistence ──────────────────────────────────────────────
 /**
@@ -175,21 +216,32 @@ export function parseFiltersFromUrl(
 }
 /**
- * Pagefind's `search()` accepts filters keyed by facet name with
- * either a single value, an array (OR), or a nested operator
- * object. We always pass the array form so multi-select works
- * within a facet without special-casing single-select.
+ * Build Pagefind's `filters` argument from internal facet state.
+ *
+ * Pagefind's array shape (`{ tag: ["a", "b"] }`) is AND by default —
+ * "page must have BOTH tags" — per
+ * https://pagefind.app/docs/js-api-filtering/ ("All filtering
+ * defaults to AND filtering"). That's the wrong UX for faceted
+ * search: clicking two checkboxes in the same group should widen
+ * the result set, not collapse it to zero. We wrap each facet in
+ * `{ any: [...] }` so multi-select within a facet is OR. Across
+ * different facets Pagefind already ANDs the keys, which matches
+ * the standard "narrow with each additional dimension" UX.
+ *
+ * Single-value selections also go through `{ any: ["x"] }` —
+ * Pagefind treats a one-element `any` identically to a bare string,
+ * so there's no behavioural delta and the code stays branch-free.
  *
  * Empty filter state → `{}` (Pagefind returns the unfiltered
- * result set). A facet with an empty array also drops out so we
- * don't accidentally narrow to "must equal nothing".
+ * result set). A facet with an empty array drops out so we don't
+ * accidentally narrow to "must equal nothing".
  */
 export function filterStateToPagefindFilters(
   filters: FilterState,
-): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+): Record<string, { any: string[] }> {
+  const out: Record<string, { any: string[] }> = {};
   for (const [name, values] of Object.entries(filters)) {
-    if (values.length > 0) out[name] = [...values];
+    if (values.length > 0) out[name] = { any: [...values] };
   }
   return out;
 }

package/src/version-redirect.ts CHANGED Viewed

@@ -35,6 +35,20 @@ export interface AxisRedirectConfig {
   defaultLocale?: string;
   /** Full set of declared locale ids. Empty/undefined → axis inactive. */
   knownLocales?: string[];
+  /**
+   * First-segment names that aren't locale/version-axis-prefixable
+   * — e.g. taxonomy index paths like `tags`, `by-type`, `by-status`.
+   * Taxonomy routes emit a single global namespace shared across
+   * all locales / versions (one `/tags/` for the whole site, not
+   * one per locale), so the axis-redirect helper must skip them.
+   * Without this skip, chip hrefs to `/<basePath>/tags/...` would
+   * 302 to `/<basePath>/<defaultLocale>/tags/...` which 404s.
+   *
+   * Each entry is the first URL segment after basePath
+   * (no leading slash). Sourced from declared
+   * `taxonomies.<name>.indexPath` in `dogsbay.config.yml`.
+   */
+  globalPrefixes?: string[];
 }
 /**
@@ -88,6 +102,15 @@ export function shouldRedirectToDefaultVersion(
   // Skip Astro / Pagefind asset paths.
   if (segments[0].startsWith("_") || segments[0] === "pagefind") return null;
+  // Skip global-namespace prefixes (taxonomy index paths and similar
+  // routes that don't live under per-locale / per-version trees).
+  // Without this, chip hrefs to `/docs/tags/concept/rag/` get
+  // redirected to `/docs/<defaultLocale>/tags/concept/rag/` which
+  // 404s — the taxonomy routes are emitted once at the unprefixed
+  // path. See plans/beta-launch-followups.md.
+  const globalPrefixes = config.globalPrefixes ?? [];
+  if (globalPrefixes.includes(segments[0])) return null;
   // Greedy axis detection — locale outermost, version next.
   const knownLocales = new Set(config.knownLocales ?? []);
   const knownVersions = new Set(config.knownVersions ?? []);