@dogsbay/format-astro 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/project.js

@@ -4,13 +4,28 @@
  * Takes ExportPage[] + NavItem[] and generates a complete Astro project
  * with static .astro pages using real Dogsbay components.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync, readdirSync, statSync, } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, cpSync, readdirSync, statSync, } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { treeToDogsbayMd } from "@dogsbay/format-dogsbay-md";
-import { treeToAstro } from "./serialize.js";
+import { treeToAstro, TONE_CLASSES } from "./serialize.js";
 import { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt } from "./llms-txt.js";
-import { normalizeBasePath, basePathSegments, buildCurrentPath } from "./base-path.js";
+import { buildSitemap, buildSitemapIndex } from "./sitemap.js";
+import { normalizeBasePath, basePathSegments, buildCurrentPath, withBasePath, parseSiteUrl, combinePrefix, } from "./base-path.js";
+/**
+ * Combined URL prefix = urlBase (Astro `base` from site.url path) +
+ * basePath (filesystem layout prefix). Every URL emitter (nav,
+ * sitemap, llms.txt, .md mirror, _headers, taxonomy) uses this for
+ * href output. Filesystem-layout consumers (mkdir, page output
+ * paths) keep using basePath alone — Astro's `base` config adds the
+ * urlBase prefix at route time.
+ *
+ * See plans/astro-base-from-site-url.md.
+ */
+function combinedPrefix(options) {
+    const { urlBase } = parseSiteUrl(options.siteUrl);
+    return combinePrefix(urlBase, normalizeBasePath(options.basePath));
+}
 import { detectLeadingNodes } from "./lead.js";
 /**
  * Recursively prefix all hrefs in a nav tree.
@@ -147,6 +162,125 @@ function buildWranglerConfig(siteName, options) {
     lines.push(`}`);
     return lines.join("\n") + "\n";
 }
+/**
+ * Build the GitHub Actions workflow YAML for `actions/deploy-pages`.
+ *
+ * The workflow:
+ *   1. Checks out the repo on every push to the default branch.
+ *   2. Installs node + pnpm at the Astro project directory, runs
+ *      `dogsbay site build` (via `pnpm dlx` since Dogsbay is a
+ *      global CLI, not a project dep), then `pnpm run build`
+ *      (which runs `astro build && pagefind`).
+ *   3. Uploads `<astroDirRel>/dist` as a Pages artifact via
+ *      `actions/upload-pages-artifact`.
+ *   4. Deploys via `actions/deploy-pages`.
+ *
+ * `astroDirRel` is the path of the Astro output relative to the
+ * repo root (typically "astro" — the default config has
+ * `output: ./astro`). Empty string is allowed when the project is
+ * flat (outputDir === projectDir); the workflow degrades naturally
+ * by omitting the `defaults: working-directory` block.
+ *
+ * Author edits — extra build steps, secrets, deploy gating — survive
+ * subsequent `dogsbay site build` runs because the file is written
+ * write-if-missing (see emitDeployArtifacts). To start over, delete
+ * the workflow file and rebuild.
+ *
+ * Note on basePath: GitHub Pages serves project sites at
+ * `https://<user>.github.io/<repo>/`. Authors who want their docs at
+ * the repo root should set `site.basePath: /<repo-name>` (or empty
+ * for user/org pages). The platform's basePath plumbing handles all
+ * URL rewriting; this workflow doesn't need to know about it.
+ */
+function buildGitHubPagesWorkflow(astroDirRel) {
+    // When the Astro output IS the project root, drop the working-
+    // directory block and reference cache + artifact paths without a
+    // prefix. This is the flat-layout case (rare for site-init flows;
+    // common for `dogsbay convert` outputs that get manually wired up).
+    const isFlat = astroDirRel === "" || astroDirRel === ".";
+    const workingDirBlock = isFlat
+        ? ""
+        : `
+    defaults:
+      run:
+        working-directory: ${astroDirRel}`;
+    const cacheDep = isFlat
+        ? "pnpm-lock.yaml"
+        : `${astroDirRel}/pnpm-lock.yaml`;
+    const artifactPath = isFlat ? "dist" : `${astroDirRel}/dist`;
+    return `# Deploy to GitHub Pages.
+# Generated by \`dogsbay site init --deploy=github-pages\` (or by
+# adding \`deploy: { target: github-pages }\` to dogsbay.config.yml
+# and running \`dogsbay site build\`). Author edits survive every
+# subsequent build — the file is never overwritten. To regenerate
+# from template, delete the file and rebuild.
+#
+# Repo settings: Settings → Pages → Source = "GitHub Actions".
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping queued runs.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest${workingDirBlock}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          # Astro 6 requires Node ^20.19.5 || >=22.12.0; pin 22 for
+          # forward-compat (Node 20 LTS is fine for Astro 5 sites
+          # but the Dogsbay scaffold targets Astro 6).
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: ${cacheDep}
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # \`dogsbay\` is a global CLI, not a project dep — pnpm dlx
+      # fetches it on demand. To pin a version, replace with e.g.
+      # \`pnpm dlx dogsbay@0.2.0-beta.18 site build\`.
+      - name: Build with Dogsbay
+        run: pnpm dlx dogsbay@beta site build
+
+      - name: Build Astro site
+        run: pnpm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${artifactPath}
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}
 /**
  * Construct the SiteConfig object that gets serialized to
  * `src/data/site.json`. Backward-compatible: existing fields keep their
@@ -187,7 +321,23 @@ function buildSiteConfig(siteName, options) {
     }
     if (options.taxonomyIndexPaths &&
         Object.keys(options.taxonomyIndexPaths).length > 0) {
-        cfg.taxonomyIndexPaths = options.taxonomyIndexPaths;
+        // Bake basePath into every emitted indexPath so consumers
+        // (TypeBadge / StatusBadge / future components) compose hrefs
+        // like `${indexPath}/<value>/` and resolve under the configured
+        // site base. Without the prefix, `/by-type/tutorial/` 404s on
+        // any site with `site.basePath` set. Caller passes raw config
+        // values (`/by-type`, `/tags`, etc.) — basePath threading is
+        // this emitter's responsibility, matching how `page.url` is
+        // already prefixed in the taxonomy data file.
+        // Taxonomy index paths are baked into site.json so components
+        // (TagList, TaxonomyIndex, TypeBadge) emit correct hrefs at
+        // runtime. Use combined so these resolve under the host's
+        // served subpath.
+        const taxoPrefix = combinedPrefix(options);
+        cfg.taxonomyIndexPaths = Object.fromEntries(Object.entries(options.taxonomyIndexPaths).map(([name, raw]) => [
+            name,
+            withBasePath(taxoPrefix, raw),
+        ]));
     }
     if (options.taxonomyDisplay &&
         Object.keys(options.taxonomyDisplay).length > 0) {
@@ -257,6 +407,74 @@ function ensureDirectoryStructure(outputDir, basePath) {
 export function emitSiteConfig(outputDir, siteName, options) {
     mkdirSync(join(outputDir, "src", "data"), { recursive: true });
     writeFileSync(join(outputDir, "src", "data", "site.json"), JSON.stringify(buildSiteConfig(siteName, options), null, 2));
+    // Auto-generated companion to astro.config.mjs. Carries the
+    // site/base values derived from dogsbay.config.yml's site.url so
+    // changes propagate without --force-rescaffolding the main
+    // astro.config.mjs (which is scaffold-once and may have author
+    // edits — custom integrations, build hooks, etc.). The main
+    // config imports `dogsbaySite` + `dogsbayBase` from here.
+    // See plans/astro-base-from-site-url.md.
+    const { origin, urlBase: astroBase } = parseSiteUrl(options.siteUrl);
+    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
+    const dogsbaySiteJson = hasSiteUrl
+        ? JSON.stringify(origin ?? options.siteUrl)
+        : "undefined";
+    const dogsbayBaseJson = astroBase ? JSON.stringify(astroBase) : "undefined";
+    // build.inlineStylesheets — defaults to "auto" (Astro's own
+    // default; matches our docs-first bias since theme.css is ~120KB
+    // and externalizing it lets the file cache cross-page). Authors
+    // wanting "always" / "never" set it via dogsbay.config.yml's
+    // build.inlineStylesheets. See docs/perf-tuning.md.
+    const dogsbayInline = options.inlineStylesheets ?? "auto";
+    writeFileSync(join(outputDir, "astro.config.dogsbay.mjs"), [
+        "// Auto-generated by `dogsbay site build` — DO NOT EDIT.",
+        "// Tracks site.url + derived Astro base + build behaviour from",
+        "// dogsbay.config.yml. Edit dogsbay.config.yml and rebuild;",
+        "// edits to this file will be overwritten on the next build.",
+        `export const dogsbaySite = ${dogsbaySiteJson};`,
+        `export const dogsbayBase = ${dogsbayBaseJson};`,
+        `export const dogsbayInlineStylesheets = ${JSON.stringify(dogsbayInline)};`,
+        "",
+    ].join("\n"));
+    // Migration check: pre-beta.20 sites have an astro.config.mjs that
+    // doesn't import the companion. Without the import, the values
+    // emitted above are unused and Astro's `base` stays unset — the
+    // exact bug this work was meant to close. Warn loudly, with the
+    // patch the user needs to apply, until astro.config.mjs is
+    // updated. We don't auto-patch because the file may have author
+    // edits (custom integrations, build hooks).
+    const astroConfigPath = join(outputDir, "astro.config.mjs");
+    if (existsSync(astroConfigPath)) {
+        const astroConfigSrc = readFileSync(astroConfigPath, "utf-8");
+        if (!astroConfigSrc.includes("astro.config.dogsbay.mjs")) {
+            console.warn([
+                "",
+                "  ⚠ astro.config.mjs is missing the dogsbay companion import.",
+                "    Without it, Astro's `base` config stays unset and assets",
+                "    served from a host subpath (GH Pages project pages,",
+                "    multi-mount Cloudflare) will 404.",
+                "",
+                "    Add these two lines to astro.config.mjs:",
+                "",
+                '      import {',
+                '        dogsbaySite,',
+                '        dogsbayBase,',
+                '        dogsbayInlineStylesheets,',
+                '      } from "./astro.config.dogsbay.mjs";',
+                "",
+                "      export default defineConfig({",
+                "        ...(dogsbaySite ? { site: dogsbaySite } : {}),",
+                "        ...(dogsbayBase ? { base: dogsbayBase } : {}),",
+                "        build: { inlineStylesheets: dogsbayInlineStylesheets },",
+                "        // ...your existing config...",
+                "      });",
+                "",
+                "    OR regenerate from template (overwrites your edits):",
+                "      dogsbay site init . --scaffold-only --force",
+                "",
+            ].join("\n"));
+        }
+    }
 }
 export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     let scaffoldFilesSkipped = 0;
@@ -271,15 +489,36 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
     // - --local outside workspace: use file: paths pointing at monorepo packages
     // - Otherwise: versioned specs (expects registry-published packages)
     const insideWs = isInsideWorkspace(outputDir);
+    // Read format-astro's own version at runtime — every @dogsbay/*
+    // package ships in lockstep at the same version (publish-beta.sh
+    // bumps them together), so format-astro's version is the right
+    // peer spec for `@dogsbay/docs-layout`, `@dogsbay/ui`, etc. in
+    // the scaffolded astro/package.json. Fixes the "hardcoded
+    // ^0.1.0" trap that caused npm install to fail post-publish.
+    const dogsbayPeerVersion = (() => {
+        try {
+            const here = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+            // Caret on a stable version, exact pin on a prerelease (npm
+            // treats `^0.2.0-beta.2` as NOT matching `0.2.0-beta.3` — the
+            // prerelease semantics force exact-or-explicit-range. Pinning
+            // prereleases avoids surprise resolves to incompatible betas.)
+            return /-/.test(pkg.version) ? pkg.version : `^${pkg.version}`;
+        }
+        catch {
+            return "^0.1.0"; // last-resort fallback
+        }
+    })();
     const dogsbayDep = (name) => {
         if (insideWs)
             return "workspace:*";
         if (options.local)
             return `file:${resolveMonorepoPkg(name)}`;
-        return "^0.1.0";
+        return dogsbayPeerVersion;
     };
     // Per-deploy-target additions to package.json
     const isCloudflare = options.deploy === "cloudflare-workers";
+    const isGitHubPages = options.deploy === "github-pages";
     const deployScripts = isCloudflare
         ? { deploy: "pnpm build && wrangler deploy" }
         : {};
@@ -305,7 +544,11 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
             },
             dependencies: {
                 astro: "^6.0.0",
-                "@astrojs/sitemap": "^3.0.0",
+                // Sitemap is emitted directly by Dogsbay into
+                // public/<basePath>/sitemap-{index,0}.xml so multi-mount
+                // deploys don't collide at the host root. We deliberately
+                // do NOT depend on @astrojs/sitemap (it hardcodes output to
+                // dist/ root, which is what we're moving away from).
                 // Pagefind is invoked from the build script (see scripts.build above).
                 // Lives in dependencies (not devDependencies) so production builds
                 // include it; the produced search index is shipped statically and
@@ -329,6 +572,13 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
                 "@dogsbay/icons": dogsbayDep("icons"),
                 "@dogsbay/elements": dogsbayDep("elements"),
             },
+            // Pin transitive Vite to 7. Vite 8 just released; Astro 6
+            // peer-deps Vite 7 and prints a warning when 8 is hoisted.
+            // Without this override npm picks up Vite 8 by default.
+            // Drop this when Astro 7 ships and bumps its peer.
+            overrides: {
+                vite: "^7",
+            },
             ...(Object.keys(deployDevDeps).length > 0
                 ? { devDependencies: deployDevDeps }
                 : {}),
@@ -347,6 +597,18 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
             scaffoldFilesSkipped++;
         }
     }
+    // GitHub Pages deploy artifacts — workflow + .nojekyll. The actual
+    // emission lives in `emitDeployArtifacts` so site-build can also
+    // call it on existing sites without going through scaffold (a user
+    // adds `deploy: github-pages` to dogsbay.config.yml and reruns
+    // `site build` to get the workflow). At scaffold-time we pass
+    // forceOverwrite=writeScaffold so `--force` regenerates from
+    // template; on regular builds it stays write-if-missing.
+    if (isGitHubPages) {
+        emitDeployArtifacts(outputDir, options, {
+            forceOverwrite: writeScaffold,
+        });
+    }
     // Generate astro.config.mjs
     // `preserveSymlinks: true` is used with --local to pin local file: deps to
     // their on-disk paths. Inside a pnpm workspace this breaks Astro's internal
@@ -358,52 +620,50 @@ export function emitSiteScaffold(outputDir, siteName, options, writeScaffold) {
       preserveSymlinks: true,
     },`
         : "";
-    // Sitemap integration is conditional: requires an absolute site URL so
-    // <loc> entries can be properly absolute. Without siteUrl, the sitemap
-    // step is skipped (the import + integration call are simply omitted from
-    // the generated config). Sitemap also filters out frontmatter-noindex pages.
-    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
-    const sitemapImport = hasSiteUrl ? `import sitemap from "@astrojs/sitemap";\n` : "";
-    // Strip any path component from site.url before emitting. The
-    // config validator already rejects `site.url` containing a path
-    // when `basePath` is non-empty (canonical URLs would double-count
-    // the prefix); this is a defensive normalisation for the case
-    // where the validator is bypassed or basePath is empty.
+    // siteUrl gates absolute-URL emission (sitemap <loc> entries,
+    // canonical tags). Without one, both are skipped — relative URLs
+    // are still correct, the sitemap is just not generated.
     //
-    // Note: we deliberately do NOT emit Astro's `base:` field. With
-    // the current file emission (pages live under
-    // `src/pages/<basePath>/...`), adding `base` would cause Astro
-    // to doubly-prefix every route. Switching to `base`-driven
-    // routing is a separate refactor — see plans/configurable-base-path.md.
-    let siteField = "";
-    if (hasSiteUrl) {
-        let originOnly;
-        try {
-            const u = new URL(options.siteUrl);
-            originOnly = `${u.protocol}//${u.host}`;
-        }
-        catch {
-            originOnly = options.siteUrl;
-        }
-        siteField = `\n  site: ${JSON.stringify(originOnly)},`;
-    }
-    const integrationsField = hasSiteUrl ? `\n  integrations: [sitemap()],` : "";
-    // astro.config.mjs — scaffold-once. Maintainer adds custom integrations.
-    // The plugin-aliases import is for the Dogsbay plugin API: each
-    // build emits `astro.config.plugins.mjs` exporting `pluginAliases`,
-    // a Vite alias map for `virtual:dogsbay-plugin-config/<id>` modules.
-    // When no plugins use defineClientConfig the map is empty and the
-    // spread is a no-op. See plans/plugin-api.md.
+    // Sitemap is emitted directly by Dogsbay (see emitSitemapFiles)
+    // into public/<basePath>/sitemap-*.xml. We deliberately do NOT
+    // wire @astrojs/sitemap here; that integration hardcodes output
+    // to dist/ root, breaking multi-mount deploys.
+    const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
+    // site.url's path component (if any) becomes Astro's `base`. The
+    // origin alone goes into `site`. This split lets dogsbay model
+    // both axes independently:
+    //   - Astro's `base` (= urlBase) controls the URL prefix Astro
+    //     bakes into HTML asset references (`<basePath>/_astro/...`)
+    //     and the routes Astro generates from src/pages.
+    //   - dogsbay's basePath controls the filesystem layout
+    //     (`src/pages/<basePath>/...`).
+    // The two compose at emit time — combining for nav hrefs,
+    // sitemap, llms.txt, etc. See plans/astro-base-from-site-url.md.
+    const { origin, urlBase: astroBase } = parseSiteUrl(options.siteUrl);
+    // astro.config.mjs — scaffold-once, but the site/base values flow
+    // through a separate auto-generated file (`astro.config.dogsbay.mjs`,
+    // emitted unconditionally below) so dogsbay-derived values stay in
+    // sync with `dogsbay.config.yml` even on existing sites where the
+    // main config is preserved. Same pattern as
+    // `astro.config.plugins.mjs` — the import line is the load-bearing
+    // bit; the auto-file is what changes.
     if (writeScaffold) {
         writeFileSync(join(outputDir, "astro.config.mjs"), `import { defineConfig } from "astro/config";
 import tailwindcss from "@tailwindcss/vite";
-${sitemapImport}import { pluginAliases, pluginFsAllow } from "./astro.config.plugins.mjs";
+import { pluginAliases, pluginFsAllow } from "./astro.config.plugins.mjs";
+import {
+  dogsbaySite,
+  dogsbayBase,
+  dogsbayInlineStylesheets,
+} from "./astro.config.dogsbay.mjs";
 
-export default defineConfig({${siteField}
+export default defineConfig({
+  ...(dogsbaySite ? { site: dogsbaySite } : {}),
+  ...(dogsbayBase ? { base: dogsbayBase } : {}),
   output: "static",
   build: {
-    inlineStylesheets: "always",
-  },${integrationsField}
+    inlineStylesheets: dogsbayInlineStylesheets,
+  },
   vite: {
     plugins: [tailwindcss()],
     resolve: {
@@ -425,6 +685,9 @@ export default defineConfig({${siteField}
     else {
         scaffoldFilesSkipped++;
     }
+    // astro.config.dogsbay.mjs is emitted by emitSiteConfig (called
+    // above and on every site build) so site/base values stay in
+    // sync without a re-scaffold. See its definition for rationale.
     // Always seed an empty astro.config.plugins.mjs so the import in
     // astro.config.mjs resolves before the first plugin-emitting
     // build. Subsequent builds replace it via emitPluginRuntime.
@@ -495,7 +758,12 @@ export default defineConfig({${siteField}
  */
 export async function emitAstroPages(pages, nav, outputDir, options) {
     const siteName = options.siteName || "Documentation";
+    // basePath = filesystem layout prefix (where pages live under
+    // src/pages/...). combined = the URL prefix HTML hrefs need
+    // (urlBase + basePath). The two diverge whenever site.url has a
+    // path component (GH Pages project pages, multi-mount Cloudflare).
     const basePath = normalizeBasePath(options.basePath);
+    const combined = combinedPrefix(options);
     const baseSegments = basePathSegments(basePath);
     // Ensure dirs exist (callers may invoke us without going through the
     // full exportAstroProject orchestrator, e.g. dogsbay convert at Step 7).
@@ -516,7 +784,11 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         // Remove existing entry for this section (full replace)
         existingNav = existingNav.filter((item) => item.label?.toLowerCase() !== siteName.toLowerCase()
             && item.label?.toLowerCase() !== section.toLowerCase());
-        const prefixedNav = prefixNavHrefs(nav, section, basePath);
+        // Nav hrefs already carry the `combined` prefix (the importer
+        // emits them via fileToHref(file, hrefPrefix=combined)).
+        // prefixNavHrefs takes the existing prefix and weaves a section
+        // segment into it.
+        const prefixedNav = prefixNavHrefs(nav, section, combined);
         const sectionLabel = siteName
             || section.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
         existingNav.push({ label: sectionLabel, children: prefixedNav });
@@ -531,13 +803,16 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
         copyAssets(options.sourceDir, outputDir, options.imageOptimization);
     }
     let generated = 0;
+    const generatedPaths = new Set();
     const pagesDir = join(outputDir, "src", "pages", ...baseSegments);
     const useImageOpt = options.imageOptimization ?? false;
-    // hrefPrefix is the same string as basePath. rewriteHref handles the
-    // empty-basePath case correctly: any link starting with "/" matches
-    // the early-return guard, so root-relative links pass through
-    // unrewritten when the site is served at host root.
-    const hrefPrefix = basePath;
+    // hrefPrefix is the COMBINED prefix (urlBase + basePath) — what
+    // rendered HTML hrefs need so internal links resolve under the
+    // host's served subpath AND under the dogsbay basePath. For
+    // simple host-apex deploys with basePath, urlBase is empty so
+    // combined === basePath (back-compat). For GH Pages project pages
+    // and multi-mount Cloudflare, combined adds the urlBase layer.
+    const hrefPrefix = combined;
     for (const page of pages) {
         try {
             // Rewrite internal hrefs to match the output URL structure
@@ -581,7 +856,23 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             const pageCategory = Array.isArray(pageMeta?.category)
                 ? pageMeta.category
                 : undefined;
-            const tagsIndexPath = options.tagsIndexPath ?? "/tags";
+            // Custom-taxonomy values lifted from frontmatter into
+            // `meta.taxonomies` by the importer (see `parseMeta` in
+            // `@dogsbay/types`). Surfaced to DocsLayout so it can emit one
+            // `<div data-pagefind-filter="<name>:<value>">` per entry — this
+            // is what makes user-declared taxonomies (`difficulty`, `team`,
+            // anything not in the five built-ins) appear as visible facet
+            // checkboxes in the search dialog. Without this passthrough
+            // they're silently dropped after the importer.
+            const pageTaxonomies = pageMeta?.taxonomies && Object.keys(pageMeta.taxonomies).length > 0
+                ? pageMeta.taxonomies
+                : undefined;
+            // `tagsIndexPath` flows to `<TagList>` for chip hrefs
+            // (`${indexPath}/${tag}/`). Caller passes the raw config value
+            // (e.g. `/tags`); we bake basePath here so chips resolve under
+            // the configured site base. Without the prefix, every tag chip
+            // 404s on any site with `site.basePath` set.
+            const tagsIndexPath = withBasePath(basePath, options.tagsIndexPath ?? "/tags");
             // Auto-lede detection. If the markdown body doesn't already
             // start with an H1 / leading paragraph, we ask DocsLayout to
             // render the frontmatter title / description at the top of
@@ -613,12 +904,20 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             // available via other means. The "Open in" deep links work
             // regardless of mirror availability — agents that can't fetch
             // the page just see the URL in their chat.
+            // pageHrefBase uses combined (urlBase + basePath) so the URL
+            // resolves correctly when the host serves dist/ at a subpath
+            // (GH Pages project page, multi-mount Cloudflare).
             const pageHrefBase = section
-                ? (basePath ? `${basePath}/${section}/${page.slug}` : `/${section}/${page.slug}`)
-                : (basePath ? `${basePath}/${page.slug}` : `/${page.slug}`);
+                ? (combined ? `${combined}/${section}/${page.slug}` : `/${section}/${page.slug}`)
+                : (combined ? `${combined}/${page.slug}` : `/${page.slug}`);
             const pageMdHref = `${pageHrefBase}.md`;
-            const pageMdAbsoluteUrl = options.siteUrl
-                ? options.siteUrl.replace(/\/$/, "") + pageMdHref
+            // For absolute URLs (the "Copy as MD" deep link), use the
+            // origin (no path) + the full combined path; siteUrl alone
+            // would double-include the urlBase since pageHrefBase already
+            // contains it.
+            const { origin } = parseSiteUrl(options.siteUrl);
+            const pageMdAbsoluteUrl = origin
+                ? origin + pageMdHref
                 : pageMdHref;
             // Markdown body for the Copy button. Reuse the same serializer
             // that produces the .md mirror so what the user copies matches
@@ -660,7 +959,10 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 "",
                 `const headings = ${JSON.stringify(page.headings || [])};`,
                 `const nav = navData;`,
-                `const currentPath = "${buildCurrentPath(basePath, section, page.slug)}";`,
+                // currentPath uses combined so it matches nav.json hrefs
+                // (which are also combined-prefixed). getPagination compares
+                // them as strings; mismatched prefixes break prev/next.
+                `const currentPath = "${buildCurrentPath(combined, section, page.slug)}";`,
                 // Filter nav to the current (locale, version) bucket
                 // before computing prev/next — without this, pagination
                 // walks the global nav and a "Next" link can leak from
@@ -684,6 +986,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `const pageType = ${JSON.stringify(pageTypeStr ?? null)};`,
                 `const pageAudience = ${JSON.stringify(pageAudience ?? null)};`,
                 `const pageCategory = ${JSON.stringify(pageCategory ?? null)};`,
+                `const pageTaxonomies = ${JSON.stringify(pageTaxonomies ?? null)};`,
                 `const tagsIndexPath = ${JSON.stringify(tagsIndexPath)};`,
                 `const llmActionsProps = ${JSON.stringify(llmActionsEnabled
                     ? {
@@ -729,6 +1032,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
                 `  pageType={pageType ?? undefined}`,
                 `  audience={pageAudience ?? undefined}`,
                 `  category={pageCategory ?? undefined}`,
+                `  taxonomies={pageTaxonomies ?? undefined}`,
                 `  autoH1={${autoH1}}`,
                 `  autoLede={${autoLede}}`,
                 `  llmActions={llmActionsProps}`,
@@ -771,6 +1075,7 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
             mkdirSync(dirname(pagePath), { recursive: true });
             writeFileSync(pagePath, pageLines.join("\n") + "\n");
             generated++;
+            generatedPaths.add(relative(outputDir, pagePath));
             // Companion .md endpoint for content negotiation. Prerendered, so
             // it's served as a static asset at runtime — no Worker overhead.
             //
@@ -811,9 +1116,43 @@ export async function emitAstroPages(pages, nav, outputDir, options) {
     // redirect target), and writing a redirect would clobber it.
     if (basePath !== "") {
         const firstHref = findFirstNavHref(nav, basePath);
-        writeFileSync(join(outputDir, "src", "pages", "index.astro"), `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
+        const indexPath = join(outputDir, "src", "pages", "index.astro");
+        writeFileSync(indexPath, `---\nreturn Astro.redirect("${firstHref}");\n---\n`);
+        generatedPaths.add(relative(outputDir, indexPath));
+    }
+    return { generated, outputNav, generatedPaths };
+}
+/**
+ * Copy each passthrough `.astro` source to its computed output path.
+ * Aborts with a clear error if the destination is already in
+ * `generatedPaths` (a generated page from `emitAstroPages` would
+ * silently overwrite the hand-authored file otherwise).
+ */
+export function emitPassthroughAstroPages(copies, outputDir, generatedPaths) {
+    if (copies.length === 0)
+        return { copied: 0 };
+    // Collision detection — a generated page and a passthrough page
+    // would write to the same file. Refuse to overwrite; tell the
+    // author exactly which two files conflict.
+    const collisions = [];
+    for (const copy of copies) {
+        if (generatedPaths.has(copy.outputRelPath)) {
+            collisions.push(copy.outputRelPath);
+        }
     }
-    return { generated, outputNav };
+    if (collisions.length > 0) {
+        throw new Error(`Passthrough Astro page collides with a generated page:\n` +
+            collisions.map((c) => `  - ${c}`).join("\n") + "\n" +
+            `Rename the .astro source or remove the colliding entry from nav.yml.`);
+    }
+    let copied = 0;
+    for (const copy of copies) {
+        const dest = join(outputDir, copy.outputRelPath);
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(copy.sourceAbs, dest);
+        copied++;
+    }
+    return { copied };
 }
 // ─── Tier 1: config-derived ─────────────────────────────────────────────
 // Files driven entirely by config + flags. Always regenerated; site
@@ -829,6 +1168,54 @@ export function emitConfigDerivedFiles(outputDir, options) {
     const hasSiteUrl = Boolean(options.siteUrl && /^https?:\/\//.test(options.siteUrl));
     writeFileSync(join(outputDir, "public", "robots.txt"), buildRobotsTxt(options, hasSiteUrl));
 }
+/**
+ * Per-deploy-target artifact emission.
+ *
+ * Called from `emitSiteScaffold` (with `forceOverwrite=writeScaffold`
+ * so `--force` regenerates from template) and from `dogsbay site
+ * build` (with `forceOverwrite=false` so an existing site can adopt
+ * a deploy target by editing config and rebuilding — the missing
+ * artifact gets created on the next build).
+ *
+ * Emit policy is the union: write when forced OR when the file is
+ * missing. Author edits to e.g. the workflow YAML survive every
+ * regular build.
+ *
+ * Currently handles `github-pages` (workflow + .nojekyll). The
+ * existing `cloudflare-workers` artifacts (wrangler.jsonc + package
+ * scripts) stay in the scaffold-only path because they overlap with
+ * scaffold-only files (package.json scripts, devDependencies). A
+ * future refactor could fold them in here too.
+ */
+export function emitDeployArtifacts(outputDir, options, opts = { forceOverwrite: false }) {
+    if (options.deploy === "github-pages") {
+        // GitHub reads workflows from <repo-root>/.github/workflows/, NOT
+        // from inside subdirectories. Use projectDir (the repo root) for
+        // the workflow file; fall back to outputDir when unset (flat
+        // `dogsbay convert` flows where the Astro project IS the repo).
+        const projectDir = options.projectDir ?? outputDir;
+        // Path of the Astro output relative to the project root. Used by
+        // the workflow's working-directory + cache-dependency-path so
+        // pnpm install / pnpm run build target the right place. Empty
+        // string when outputDir === projectDir (flat layout).
+        const astroDirRel = relative(projectDir, outputDir).replace(/\\/g, "/");
+        const workflowPath = join(projectDir, ".github", "workflows", "deploy.yml");
+        if (opts.forceOverwrite || !existsSync(workflowPath)) {
+            mkdirSync(dirname(workflowPath), { recursive: true });
+            writeFileSync(workflowPath, buildGitHubPagesWorkflow(astroDirRel));
+        }
+        // .nojekyll — must exist in the deployed artifact root so GH
+        // Pages skips Jekyll's `_underscored-paths` filter (Astro's
+        // `_astro/` chunk dir gets eaten otherwise). Lives inside the
+        // Astro project's `public/` so it's copied into `dist/` at
+        // build time.
+        const nojekyllPath = join(outputDir, "public", ".nojekyll");
+        mkdirSync(dirname(nojekyllPath), { recursive: true });
+        if (opts.forceOverwrite || !existsSync(nojekyllPath)) {
+            writeFileSync(nojekyllPath, "");
+        }
+    }
+}
 /**
  * Emit `src/data/switcherMap.json` describing per-page
  * version + locale equivalents. Always writes the file —
@@ -845,7 +1232,10 @@ export function emitConfigDerivedFiles(outputDir, options) {
  * baseline page in a multi-version site).
  */
 export function emitSwitcherMap(pages, outputDir, options) {
-    const basePath = normalizeBasePath(options.basePath);
+    // Switcher URLs use combined so the link the dropdown emits
+    // resolves under the host's served subpath (GH Pages project
+    // pages, multi-mount Cloudflare).
+    const combined = combinedPrefix(options);
     const dataDir = join(outputDir, "src", "data");
     const outPath = join(dataDir, "switcherMap.json");
     // Detect axis activation by inspecting the data the loader
@@ -884,7 +1274,7 @@ export function emitSwitcherMap(pages, outputDir, options) {
         const variant = {
             ...(ms.locale !== undefined ? { locale: ms.locale } : {}),
             ...(ms.version !== undefined ? { version: ms.version } : {}),
-            url: `${basePath}/${page.slug}`,
+            url: `${combined}/${page.slug}`,
         };
         if (!byLogicalKey[key])
             byLogicalKey[key] = [];
@@ -962,6 +1352,10 @@ export function emitMissingTranslationStubs(pages, outputDir, options) {
         return;
     const basePath = normalizeBasePath(options.basePath);
     const baseSegments = basePathSegments(basePath);
+    // combined drives the redirect URL (the user-facing path they
+    // get bounced to); basePath stays the filesystem path under
+    // src/pages/ where the stub lives.
+    const combined = combinedPrefix(options);
     // Index existing pages by (slug after locale segment) so we
     // can detect missing translations cheaply. Key shape:
     // `<other-axis-prefix>/<originalSlug>` where other-axis-prefix
@@ -995,7 +1389,7 @@ export function emitMissingTranslationStubs(pages, outputDir, options) {
             const targetUrl = `${basePath}/${targetSlug}`;
             if (existingByUrl.has(targetUrl))
                 continue; // already translated
-            const defaultUrl = `${basePath}/${defaultPage.slug}`;
+            const defaultUrl = `${combined}/${defaultPage.slug}`;
             const filePath = join(outputDir, "src", "pages", ...baseSegments, ...targetSlug.split("/"));
             // Ensure parent dir exists; write a redirect-stub Astro
             // file. Adding `.astro` to the leaf turns it into a
@@ -1037,10 +1431,20 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     if (options.llmsTxt !== false) {
         emitLlmsTxtFiles(outputDir, siteName, options, outputNav, pages);
         // public/_headers — Cloudflare Workers / Pages convention. Adds an
-        // RFC 8288 Link header pointing agents at /llms.txt without parsing
-        // HTML. Emitted alongside llms.txt so the two files travel together.
+        // RFC 8288 Link header pointing agents at this mount's llms.txt
+        // (basePath-prefixed) without parsing HTML. Emitted alongside
+        // llms.txt so the two files travel together.
         mkdirSync(join(outputDir, "public"), { recursive: true });
-        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile());
+        // _headers Link header points at the per-mount llms.txt at
+        // <combined>/llms.txt — the URL agents would actually fetch.
+        writeFileSync(join(outputDir, "public", "_headers"), buildHeadersFile(combinedPrefix(options)));
+    }
+    // Sitemap — emitted by Dogsbay (not @astrojs/sitemap) into
+    // public/<basePath>/sitemap-{index,0}.xml so multi-mount deploys
+    // don't collide at host root. Gated on a valid http(s) siteUrl
+    // because <loc> entries must be absolute.
+    if (options.siteUrl && /^https?:\/\//.test(options.siteUrl)) {
+        emitSitemapFiles(outputDir, options, pages);
     }
     // src/middleware.ts — Tier 1 (always update). Drives both the
     // `Accept: text/markdown` content-negotiation rewrite (via
@@ -1059,12 +1463,29 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
     const localeRedirectOn = options.defaultLocale !== undefined && knownLocales.length >= 2;
     const axisRedirectOn = versionRedirectOn || localeRedirectOn;
     if (mdMirrorOn || axisRedirectOn) {
+        // Taxonomy index paths share a single global namespace across
+        // locales / versions (one `/tags/` for the whole site, not one
+        // per locale). The redirect helper has to know to skip them or
+        // it will 302 chip hrefs to non-existent locale-prefixed routes.
+        // Strip leading `/` and pull just the first segment so a config
+        // like `/tags` becomes the global-prefix entry `tags`.
+        const globalPrefixes = [];
+        if (options.taxonomyIndexPaths) {
+            for (const raw of Object.values(options.taxonomyIndexPaths)) {
+                const first = raw.replace(/^\/+/, "").split("/")[0];
+                if (first)
+                    globalPrefixes.push(first);
+            }
+        }
         mkdirSync(join(outputDir, "src"), { recursive: true });
         writeFileSync(join(outputDir, "src", "middleware.ts"), buildMiddlewareSource({
             mdMirror: mdMirrorOn,
             axisRedirect: axisRedirectOn
                 ? {
-                    basePath: normalizeBasePath(options.basePath),
+                    // Middleware compares paths against the request URL,
+                    // which carries the host's served subpath — so use the
+                    // combined prefix here.
+                    basePath: combinedPrefix(options),
                     ...(versionRedirectOn
                         ? {
                             defaultVersion: options.defaultVersion,
@@ -1077,6 +1498,7 @@ export function emitAgentReadinessFiles(pages, outputNav, outputDir, siteName, o
                             knownLocales,
                         }
                         : {}),
+                    ...(globalPrefixes.length > 0 ? { globalPrefixes } : {}),
                 }
                 : undefined,
         }));
@@ -1137,21 +1559,37 @@ function buildRobotsTxt(options, hasSiteUrl) {
     const aiInput = options.aiInput ?? "yes";
     const aiTrain = options.aiTrain ?? "no";
     const contentSignal = `Content-Signal: search=${search}, ai-input=${aiInput}, ai-train=${aiTrain}\n`;
-    const sitemap = hasSiteUrl
-        ? `Sitemap: ${options.siteUrl.replace(/\/$/, "")}/sitemap-index.xml\n`
+    // Per-mount sitemap path: each Dogsbay site emits its sitemap
+    // index under <basePath>/, so robots.txt must point there too.
+    // (Multi-mount deploys end up with one robots.txt per site at
+    // their respective hosts / paths; each correctly references its
+    // own mount's sitemap-index.)
+    // Sitemap URL = origin + combined + /sitemap-index.xml. Use the
+    // origin (no path) from site.url and the combined prefix (urlBase
+    // + basePath); siteUrl could itself include a path component when
+    // hosting on a subpath (GH Pages project page), so we strip it
+    // here to avoid double-counting.
+    const { origin } = parseSiteUrl(options.siteUrl);
+    const sitemap = hasSiteUrl && origin
+        ? `Sitemap: ${origin}${withBasePath(combinedPrefix(options), "/sitemap-index.xml")}\n`
         : "";
     return `User-agent: *\nAllow: /\n${contentSignal}${sitemap}`;
 }
 /**
  * Build the contents of `public/_headers` (Cloudflare Pages / Workers
  * Static Assets convention). Emits a global RFC 8288 Link header
- * pointing at the site's llms.txt index, so agents don't need to
+ * pointing at this mount's llms.txt index, so agents don't need to
  * parse HTML to discover the LLM-friendly content listing.
+ *
+ * The Link target is basePath-prefixed (`</docs/llms.txt>` for a
+ * `/docs` mount) — matches where the platform actually emits
+ * llms.txt under the per-mount layout.
  */
-function buildHeadersFile() {
+function buildHeadersFile(basePath) {
+    const llmsHref = withBasePath(basePath, "/llms.txt");
     return [
         "/*",
-        '  Link: </llms.txt>; rel="describedby"; type="text/plain"',
+        `  Link: <${llmsHref}>; rel="describedby"; type="text/plain"`,
         "",
     ].join("\n");
 }
@@ -1160,20 +1598,28 @@ function buildMiddlewareSource(config) {
         "// AUTO-GENERATED by `dogsbay site build` — do not edit.",
         "// Composes the docs-layout middleware helpers.",
         "//",
-        "// Markdown content negotiation:",
-        "//   This middleware fires on every request, but in Astro's static",
-        "//   prerender mode (output: \"static\") request headers are NOT",
-        "//   forwarded — Astro warns about \"Astro.request.headers was used",
-        "//   when rendering...\" and serves a prerendered HTML response.",
-        "//   That means `Accept: text/markdown` negotiation only kicks in",
-        "//   under SSR (output: \"server\") or via an edge function on the",
-        "//   deployment layer (Cloudflare Worker, Netlify Edge, etc.).",
-        "//   For pure-static deploys, agents should follow the page's",
-        "//   <link rel=\"alternate\" type=\"text/markdown\"> href to fetch",
-        "//   the .md mirror directly (e.g. /docs.md).",
+        "// Static-prerender guard:",
+        "//   In Astro's static output mode, this middleware is invoked",
+        "//   for every prerendered route at build time. Reading",
+        "//   `context.request.headers` there triggers an Astro warning",
+        "//   per page (\"Astro.request.headers was used during static",
+        "//   render\"), which floods `dogsbay site build` / `site preview`",
+        "//   output. Worse, the negotiation can't actually happen at",
+        "//   build time — there's no runtime client whose Accept header",
+        "//   we'd be honoring.",
+        "//",
+        "//   We guard with `context.isPrerendered` so prerendered routes",
+        "//   short-circuit to `next()` immediately. At runtime in static",
+        "//   deploys, middleware doesn't fire at all (no server); at",
+        "//   runtime in SSR / hybrid deploys, only dynamic routes fire,",
+        "//   which is exactly when negotiation makes sense.",
         "//",
-        "//   The Cloudflare-Worker-driven full fix is tracked in",
-        "//   plans/cloudflare-deploy-content-negotiation.md.",
+        "// Markdown content negotiation:",
+        "//   For pure-static deploys, `Accept: text/markdown` is honored",
+        "//   by the platform (Cloudflare _headers + Worker, Netlify Edge",
+        "//   functions). Agents that can't send Accept headers should",
+        "//   follow the page's <link rel=\"alternate\" type=\"text/markdown\">",
+        "//   to fetch the .md mirror directly (e.g. /docs.md).",
         'import { defineMiddleware } from "astro:middleware";',
     ];
     if (config.mdMirror) {
@@ -1187,6 +1633,11 @@ function buildMiddlewareSource(config) {
         lines.push(`const AXIS_REDIRECT_CONFIG = ${JSON.stringify(config.axisRedirect, null, 2)};`, "");
     }
     lines.push("export const onRequest = defineMiddleware((context, next) => {");
+    // Skip prerendered routes — see file-top comment for the rationale.
+    // Avoids per-page Astro.request.headers warnings during build, and
+    // matches runtime semantics (middleware doesn't fire on prerendered
+    // routes when deployed).
+    lines.push("  if (context.isPrerendered) return next();");
     lines.push("  const url = new URL(context.request.url);");
     if (config.mdMirror) {
         lines.push('  const accept = context.request.headers.get("accept");', "  const mdTarget = shouldRewriteToMarkdown(accept, url.pathname);", "  if (mdTarget) return context.rewrite(mdTarget);");
@@ -1218,8 +1669,18 @@ function buildMdEndpoint(page, sourceRel) {
     ].join("\n");
 }
 /**
- * Emit `public/llms.txt`, `public/llms-full.txt`, and per-section
- * `public/<dir>/llms.txt` files for the site.
+ * Emit per-mount llms.txt + llms-full.txt + per-section indexes.
+ *
+ * Files live under `public/<basePath>/...` so multiple Dogsbay sites
+ * can mount on the same host (`/docs/llms.txt` + `/api/llms.txt` +
+ * `/handbook/llms.txt`) without colliding at the root. When basePath
+ * is empty, this collapses to `public/llms.txt` — the single-site
+ * llmstxt.org-spec layout.
+ *
+ * The host root `/llms.txt` is intentionally NOT emitted by the
+ * platform: it's the user's umbrella file, analogous to
+ * `sitemap-index.xml`. Multi-mount deploys hand-write a top-level
+ * `/llms.txt` that links to each per-mount index.
  *
  * Per-section files are written for every top-level nav group that
  * resolves to a site directory (either via `group.href` or via the
@@ -1231,26 +1692,64 @@ function emitLlmsTxtFiles(outputDir, siteName, options, nav, pages) {
         description: options.description,
         siteUrl: options.siteUrl,
     };
-    const publicDir = join(outputDir, "public");
-    mkdirSync(publicDir, { recursive: true });
-    const hrefPrefix = normalizeBasePath(options.basePath);
-    writeFileSync(join(publicDir, "llms.txt"), buildLlmsTxt(siteConfig, nav, pages, { hrefPrefix }));
-    writeFileSync(join(publicDir, "llms-full.txt"), buildLlmsFullTxt(siteConfig, nav, pages, {
+    // hrefPrefix is the COMBINED prefix — used for the URL paths that
+    // appear inside the llms.txt body (so agents fetch the correct
+    // host-relative URLs). Filesystem layout uses basePath alone:
+    // `public/<basePath>/llms.txt` matches the existing per-mount
+    // delivery shape.
+    const hrefPrefix = combinedPrefix(options);
+    const basePath = normalizeBasePath(options.basePath);
+    const baseSegments = basePathSegments(basePath);
+    const mountDir = join(outputDir, "public", ...baseSegments);
+    mkdirSync(mountDir, { recursive: true });
+    writeFileSync(join(mountDir, "llms.txt"), buildLlmsTxt(siteConfig, nav, pages, { hrefPrefix }));
+    writeFileSync(join(mountDir, "llms-full.txt"), buildLlmsFullTxt(siteConfig, nav, pages, {
         summary: "body",
         serializePage: serializePageMd,
         hrefPrefix,
     }));
+    // Per-section files: `deriveSectionDir` returns a host-absolute
+    // path (already includes basePath because nav hrefs do). Join it to
+    // public/ directly — joining onto mountDir would double-prefix into
+    // `public/<basePath>/<basePath>/<section>/llms.txt`.
     for (const group of nav) {
         if (!group.children || group.children.length === 0)
             continue;
         const dir = deriveSectionDir(group);
         if (!dir)
             continue;
-        const sectionPath = join(publicDir, dir, "llms.txt");
+        const sectionPath = join(outputDir, "public", dir, "llms.txt");
         mkdirSync(dirname(sectionPath), { recursive: true });
         writeFileSync(sectionPath, buildSectionLlmsTxt(siteConfig, group, pages, { hrefPrefix }));
     }
 }
+/**
+ * Emit per-mount sitemap files.
+ *
+ * Writes `public/<basePath>/sitemap-index.xml` + `sitemap-0.xml`.
+ * The index lists the single sub-sitemap today; future splits add
+ * more sub-sitemap entries as the page count grows past
+ * sitemaps.org's 50K-URL recommendation.
+ *
+ * Caller has already guarded on a valid http(s) `siteUrl` — without
+ * one, `<loc>` entries can't be absolute and crawlers reject the
+ * file. Skip emission rather than write a broken sitemap.
+ */
+function emitSitemapFiles(outputDir, options, pages) {
+    // Filesystem path uses basePath (sitemap files live in
+    // public/<basePath>/sitemap-*.xml). The URL prefix encoded into
+    // each <loc> uses combined so the absolute URLs resolve under the
+    // host's served subpath. buildSitemap strips path off siteUrl
+    // internally, so passing siteUrl + combined as basePath gives
+    // origin + combined as the final URL.
+    const basePath = normalizeBasePath(options.basePath);
+    const combined = combinedPrefix(options);
+    const baseSegments = basePathSegments(basePath);
+    const mountDir = join(outputDir, "public", ...baseSegments);
+    mkdirSync(mountDir, { recursive: true });
+    writeFileSync(join(mountDir, "sitemap-0.xml"), buildSitemap(pages, { siteUrl: options.siteUrl, basePath: combined }));
+    writeFileSync(join(mountDir, "sitemap-index.xml"), buildSitemapIndex({ siteUrl: options.siteUrl, basePath: combined }));
+}
 /**
  * Pick a directory under `public/` for a top-level nav group. Prefers
  * the group's own href (already a `/docs/x/y` path); otherwise falls
@@ -1328,6 +1827,11 @@ function copyComponents(outputDir) {
         "response-tabs", "schema-viewer", "code-samples", "copy-button",
         "markdown-example",
         "accordion", "link-card", "avatar", "math",
+        // Icon resolves @ui/icon/Icon.astro → built-time SVG inlining
+        // via @dogsbay/icons. Used by `:::cards` `{icon=...}` and the
+        // inline `:icon[name]` directive. Without this entry every page
+        // emitting the icon import 500s with "module not found".
+        "icon",
     ];
     for (const name of needed) {
         const src = join(componentsSource, name);
@@ -1382,6 +1886,32 @@ function copyAssets(sourceDir, outputDir, imageOptimization) {
     catch { /* source may not exist */ }
 }
 // ── CSS generation (ported from import-mkdocs.ts) ───────
+/**
+ * Build the `@source inline("...")` directive that pins the
+ * grid-tone palette into the generated stylesheet.
+ *
+ * Why we need it: tone classes like `bg-primary/10` only appear in
+ * `.astro` pages emitted by Dogsbay's grid-item serializer. When
+ * Tailwind's content scanner doesn't pick them up — because the
+ * page lives outside the default scan globs, or because a class
+ * is composed at the boundary of an interpolation — they get
+ * purged. Result observed in dogsbay-docs-markdown audit: half
+ * the grid demo cells render with no background. Pinning forces
+ * generation regardless of scanner reach.
+ *
+ * Single source of truth: derived from TONE_CLASSES so any new
+ * tone added to the palette is automatically safelisted.
+ */
+function buildToneSafelist() {
+    const seen = new Set();
+    for (const classes of Object.values(TONE_CLASSES)) {
+        for (const cls of classes.split(/\s+/)) {
+            if (cls)
+                seen.add(cls);
+        }
+    }
+    return [...seen].sort().join(" ");
+}
 function generateGlobalCss() {
     return `@import "tailwindcss";
 @import "./theme.css";
@@ -1390,6 +1920,14 @@ function generateGlobalCss() {
 @source "../../node_modules/@dogsbay/ui/src";
 @source "../../node_modules/@dogsbay/docs-layout/src";
 
+/* Pin the grid-tone palette. These classes are emitted into
+   markdown-generated .astro pages by the grid-item serializer
+   (TONE_CLASSES in @dogsbay/format-astro). Without inlining,
+   opacity-modified utilities like bg-primary/10 get purged when
+   Tailwind doesn't see them in the scanned globs, leaving grid
+   demo cells with no visible background. */
+@source inline("${buildToneSafelist()}");
+
 /* Prose typography for rendered content */
 .docs-prose {
   line-height: 1.7;