npm - @dogsbay/docs-layout - Versions diffs - 0.2.0-beta.4 → 0.2.0-beta.40 - Mend

@dogsbay/docs-layout 0.2.0-beta.4 → 0.2.0-beta.40

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 (5) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.40",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.4",
-    "@dogsbay/primitives": "0.2.0-beta.4"
+    "@dogsbay/ui": "0.2.0-beta.40",
+    "@dogsbay/primitives": "0.2.0-beta.40"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/DocsLayout.astro CHANGED Viewed

@@ -112,7 +112,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 +133,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 +271,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,
@@ -376,7 +408,7 @@ const {
   editUrl,
   lastUpdated,
   copyright,
-  favicon = "/favicon.ico",
+  favicon,
   ogImage,
   defaultOgImage,
   ogType = "article",
@@ -384,11 +416,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 +437,7 @@ const {
   pageType,
   audience,
   category,
+  taxonomies,
   taxonomyIndexPaths,
   taxonomyDisplay,
   autoH1,
@@ -428,6 +468,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 +503,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
@@ -510,11 +576,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 +606,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 +675,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>
@@ -709,9 +792,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 +824,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 +920,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/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;
@@ -218,7 +223,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;

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/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 ?? []);