npm - @dogsbay/docs-layout - Versions diffs - 0.2.0-beta.8 → 0.2.0-beta.81 - Mend

@dogsbay/docs-layout 0.2.0-beta.8 → 0.2.0-beta.81

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.8",
+  "version": "0.2.0-beta.81",
   "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.8",
-    "@dogsbay/primitives": "0.2.0-beta.8"
+    "@dogsbay/ui": "0.2.0-beta.81",
+    "@dogsbay/primitives": "0.2.0-beta.81"
   },
   "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>
@@ -676,6 +792,7 @@ const siteIcon = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"
             {!hideSearch && (
               <SearchDialog
                 pagefindUrl={pagefindUrl}
+                navUrl={basePath ? `${basePath}/_dogsbay/nav.json` : "/_dogsbay/nav.json"}
                 taxonomyDisplay={taxonomyDisplay}
               />
             )}
@@ -709,9 +826,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 +858,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 +954,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>