@dogsbay/docs-layout 0.2.0-beta.113 → 0.2.0-beta.115

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.113",
+  "version": "0.2.0-beta.115",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -25,13 +25,14 @@
     "./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.113",
-    "@dogsbay/ui": "0.2.0-beta.113"
+    "@dogsbay/primitives": "0.2.0-beta.115",
+    "@dogsbay/ui": "0.2.0-beta.115"
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",

package/src/DocsLayout.astro

@@ -197,6 +197,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">`
@@ -501,6 +507,7 @@ 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",
@@ -1072,6 +1079,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}

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