dogsbay 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/commands/site-dev.js

@@ -1,24 +1,34 @@
 /**
  * `dogsbay site dev` and `dogsbay site preview` — thin wrappers that
- * run `dogsbay site build` once, then hand control over to the Astro
- * CLI inside the site directory.
+ * run `dogsbay site build`, watch content for changes, and hand
+ * control over to the Astro CLI inside the site directory.
  *
- *   dev      → astro dev      (live HMR for already-built pages)
- *   preview  → astro build && astro preview
+ *   dev      → astro dev               (live HMR for already-built pages)
+ *   preview  → <pm> run build → astro preview
  *
  * The site dir is found by locating `dogsbay.config.{yml,yaml,json}`
- * at or above cwd (or via --config). `npm run build` (the user's
- * existing script) is *not* what runs here — we shell out to `astro`
- * directly so this works whether the user uses pnpm / npm / yarn.
+ * at or above cwd (or via --config).
  *
- * Content file-watching is deferred. Today, editing source markdown
- * requires re-running `dogsbay site build` manually; Astro's dev
- * server reloads when the generated `.astro` files change.
+ * site dev shells `npx astro dev` directly — fast, no script
+ * indirection. site preview needs the production build to match
+ * what's actually deployed, which means running the scaffolded
+ * package.json `build` script (chains `astro build && pagefind
+ * --site dist` so Cmd+K search works in the previewed dist/). The
+ * package manager is auto-detected (pnpm if on PATH, otherwise npm).
+ *
+ * `site dev` also installs a content watcher that re-runs
+ * `dogsbay site build` whenever a markdown / yaml / json file under
+ * any configured source path changes (or `dogsbay.config.yml`
+ * itself). Astro's own dev server then hot-reloads the regenerated
+ * `.astro` pages. Without this, NEW files in `content/` weren't
+ * picked up by site dev — only edits to existing files surfaced
+ * (because Astro's watcher only sees `astro/src/`).
  */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import pc from "picocolors";
+import chokidar from "chokidar";
 import { findConfig, loadConfig, resolveOutputDir } from "../config/index.js";
 import { siteBuild } from "./site-build.js";
 const defaultRunner = (siteRoot, args) => new Promise((resolve) => {
@@ -32,6 +42,18 @@ const defaultRunner = (siteRoot, args) => new Promise((resolve) => {
         resolve(1);
     });
 });
+const defaultBuildRunner = (siteRoot) => new Promise((resolve) => {
+    const pm = pickPackageManager();
+    const child = spawn(pm, ["run", "build"], {
+        cwd: siteRoot,
+        stdio: "inherit",
+    });
+    child.on("exit", (code) => resolve(code ?? 0));
+    child.on("error", (err) => {
+        console.error(pc.red(`Error: failed to spawn ${pm} run build: ${err.message}`));
+        resolve(1);
+    });
+});
 /**
  * Pick the first available package manager from a preference list.
  * Defaults to pnpm (matches the dogsbay tooling chain); falls back
@@ -63,18 +85,28 @@ function runPackageManagerInstall(pm, cwd) {
     });
 }
 export async function siteDev(cwd, options, runner = defaultRunner) {
-    const siteRoot = await prepareForAstro(cwd, options);
-    const code = await runner(siteRoot, ["dev"]);
-    process.exit(code);
+    const { siteRoot, outputDir } = await prepareForAstro(cwd, options);
+    const stopWatcher = startContentWatcher(siteRoot, outputDir, options);
+    try {
+        const code = await runner(outputDir, ["dev"]);
+        stopWatcher();
+        process.exit(code);
+    }
+    catch (err) {
+        stopWatcher();
+        throw err;
+    }
 }
-export async function sitePreview(cwd, options, runner = defaultRunner) {
-    const siteRoot = await prepareForAstro(cwd, options);
-    // Two-step: produce dist/ then serve it. Each spawn is independent
-    // so we can still surface its exit code cleanly.
-    const buildCode = await runner(siteRoot, ["build"]);
+export async function sitePreview(cwd, options, runner = defaultRunner, buildRunner = defaultBuildRunner) {
+    const { outputDir } = await prepareForAstro(cwd, options);
+    // Two-step: produce dist/ via the scaffolded `build` script
+    // (astro build + pagefind), then serve it via astro preview. The
+    // build script is the source of truth — `astro build` alone would
+    // skip pagefind and Cmd+K search in the previewed dist/ would 404.
+    const buildCode = await buildRunner(outputDir);
     if (buildCode !== 0)
         process.exit(buildCode);
-    const previewCode = await runner(siteRoot, ["preview"]);
+    const previewCode = await runner(outputDir, ["preview"]);
     process.exit(previewCode);
 }
 async function prepareForAstro(cwd, options) {
@@ -110,14 +142,140 @@ async function prepareForAstro(cwd, options) {
     if (!options.noBuild) {
         // Drafts visible during local preview — site dev is the writer's
         // iteration loop. Production `dogsbay site build` filters drafts.
-        // Default mode is primary-only; `--full` opts into the publish
-        // matrix for previewing switcher chrome.
+        // site dev defaults to primary-only for fast iteration; --full
+        // opts into the publish matrix for previewing switcher chrome.
+        // (Production `dogsbay site build` defaults to full matrix; only
+        // site dev / preview default to primary-only.)
         await siteBuild(siteRoot, {
             includeDrafts: true,
-            publish: options.full === true,
+            primaryOnly: options.full !== true,
         });
     }
-    return outputDir;
+    return { siteRoot, outputDir };
+}
+/**
+ * Watch the project's content paths + config file, and re-run
+ * `dogsbay site build` whenever something changes. Astro's own
+ * watcher then picks up the regenerated `astro/src/pages/*.astro`
+ * files and hot-reloads.
+ *
+ * Returns a cleanup fn that closes all the watchers.
+ *
+ * Debounces aggressively — many editors fire 3-5 fs events per save
+ * (write + rename + close-write etc.), and a single Vim save bursts
+ * across multiple files. 300ms is the sweet spot: low enough that
+ * the user feels the rebuild as immediate, high enough to coalesce
+ * a save burst into one rebuild.
+ */
+function startContentWatcher(siteRoot, outputDir, options) {
+    // Re-load the config to know which paths to watch. We load it
+    // from disk on first event too (so config edits update the watch
+    // set on the fly).
+    let config = loadConfig(findOrFail(siteRoot, options.config));
+    // chokidar (vs Node's fs.watch) — fs.watch with `recursive: true`
+    // on Linux drops events from atomic-replace editor saves (Vim,
+    // VS Code, Helix all write tmp + rename), so nav.yml edits never
+    // surfaced as [dogsbay] rebuilds. chokidar handles atomic-replace
+    // correctly because it watches paths by name and re-arms on
+    // rename. `awaitWriteFinish` further coalesces multi-event saves
+    // into a single emit.
+    //
+    // Watch siteRoot recursively + each declared source path. The
+    // top-level `ignored` patterns keep us out of the output dir
+    // (otherwise rebuilds would self-trigger), VCS metadata, OS
+    // junk, and editor swap files.
+    const watchPaths = collectWatchPaths(siteRoot, config);
+    const watcher = chokidar.watch(watchPaths, {
+        ignoreInitial: true,
+        ignored: [
+            /(^|[\\/])\.git([\\/]|$)/,
+            /(^|[\\/])node_modules([\\/]|$)/,
+            /(^|[\\/])astro([\\/]|$)/,
+            /(^|[\\/])dist([\\/]|$)/,
+            /(^|[\\/])\.dogsbay([\\/]|$)/,
+            /\.swp$/,
+            /\.swo$/,
+            /~$/,
+            /\.DS_Store$/,
+        ],
+        awaitWriteFinish: {
+            stabilityThreshold: 50,
+            pollInterval: 10,
+        },
+    });
+    // Debounced rebuild loop. If a build is in flight when a new
+    // event arrives, mark dirty + rebuild after the current one
+    // finishes. Avoids overlapping builds racing on the same files.
+    let timer = null;
+    let building = false;
+    let dirty = false;
+    const scheduleBuild = () => {
+        dirty = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(runBuild, 300);
+    };
+    const runBuild = async () => {
+        if (building)
+            return; // a build is in flight; the dirty flag handles re-run
+        if (!dirty)
+            return;
+        dirty = false;
+        building = true;
+        try {
+            console.log(pc.cyan("[dogsbay] content changed — rebuilding…"));
+            // Reload config to pick up dogsbay.config.yml edits.
+            config = loadConfig(findOrFail(siteRoot, options.config));
+            // Re-arm any newly-added source paths (chokidar dedupes
+            // already-watched roots internally).
+            const newPaths = collectWatchPaths(siteRoot, config);
+            watcher.add(newPaths);
+            await siteBuild(siteRoot, {
+                includeDrafts: true,
+                primaryOnly: options.full !== true,
+            });
+            console.log(pc.green("[dogsbay] rebuild complete"));
+        }
+        catch (err) {
+            console.error(pc.red(`[dogsbay] rebuild failed: ${err.message}`));
+        }
+        finally {
+            building = false;
+            // Coalesced changes during the build → run again.
+            if (dirty)
+                setImmediate(runBuild);
+        }
+    };
+    watcher.on("all", (_event, _path) => scheduleBuild());
+    // Diagnostic: show what's being watched on startup.
+    console.log(pc.gray(`[dogsbay] watching ${watchPaths.length} path${watchPaths.length === 1 ? "" : "s"} for content changes`));
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        void watcher.close();
+    };
+}
+/**
+ * Collect the absolute paths chokidar should watch: the site root
+ * (so `dogsbay.config.yml` edits trigger a reload) plus every
+ * declared `content.sources[].path`. Skips entries that don't exist
+ * on disk yet — chokidar would otherwise log a noisy ENOENT.
+ */
+function collectWatchPaths(siteRoot, config) {
+    const out = new Set();
+    if (existsSync(siteRoot))
+        out.add(siteRoot);
+    for (const source of config.content?.sources ?? []) {
+        if (typeof source.path === "string") {
+            const abs = resolve(siteRoot, source.path);
+            if (existsSync(abs))
+                out.add(abs);
+        }
+    }
+    return [...out];
+}
+function findOrFail(siteRoot, explicit) {
+    return resolveConfigPath(siteRoot, explicit);
 }
 function resolveConfigPath(startDir, explicit) {
     if (explicit) {

package/dist/commands/site-init.js

@@ -101,61 +101,214 @@ export async function siteInit(targetDir, options) {
     }
     // Emit the static scaffold into the configured output dir
     // (default ./astro). The project root keeps only the config and
-    // human-edited files (content/, theme/, public/).
+    // human-edited files (content/, theme/, public/). projectDir
+    // (= absTarget) lets deploy emitters write artifacts that GitHub
+    // Actions reads from the repo root rather than the Astro subdir.
     const outputDir = resolveOutputDir(config, configPath);
     const astroOpts = configToAstroOptions(config);
+    astroOpts.projectDir = absTarget;
     if (options.local)
         astroOpts.local = true;
     emitSiteScaffold(outputDir, config.site.name, astroOpts, true);
     // Seed starter content so the first `dogsbay site build` succeeds
-    // without manual intervention. Only writes when this is a fresh
-    // init (writeConfig=true; scaffold-only consumers already have
-    // content) and the content dir doesn't exist yet — never
-    // overwrites user files. See plans/beta-launch-followups.md.
-    let starterContentPath = null;
+    // without manual intervention. Writes index.md, getting-started.md,
+    // and nav.yml when (a) this is a fresh init (writeConfig=true;
+    // scaffold-only consumers already have content) and (b) the
+    // content dir doesn't exist yet. Never overwrites user files. See
+    // plans/beta-launch-followups.md.
+    let starterContentPaths = [];
     if (writeConfig) {
-        starterContentPath = seedStarterContent(absTarget, config);
+        starterContentPaths = seedStarterContent(absTarget, config);
     }
-    printNextSteps(absTarget, outputDir, config, starterContentPath);
+    printNextSteps(absTarget, outputDir, config, starterContentPaths);
 }
 /**
- * Create a starter `<content>/index.md` if the content dir doesn't
- * already exist. Returns the path written, or null when nothing
- * was created (dir already populated). Never overwrites.
+ * Create a starter content set if the content dir doesn't already
+ * exist. Writes `index.md`, `getting-started.md`, and `nav.yml`
+ * so the user has a working multi-page site with a navigation
+ * structure to learn from. Returns the list of paths written, or
+ * an empty array when nothing was created. Never overwrites.
  */
 function seedStarterContent(absTarget, config) {
     const sources = config.content.sources ?? [];
     const first = sources[0];
     if (!first?.path)
-        return null;
+        return [];
     const contentDir = isAbsolute(first.path)
         ? first.path
         : join(absTarget, first.path);
     if (existsSync(contentDir))
-        return null; // user already has content
+        return []; // user already has content
     mkdirSync(contentDir, { recursive: true });
+    const written = [];
+    const siteName = config.site.name?.trim() || "your documentation site";
+    const basePath = config.site.basePath ?? "/docs";
     const indexPath = join(contentDir, "index.md");
     writeFileSync(indexPath, `---
-title: ${config.site.name || "Welcome"}
+title: Welcome
 description: Edit content/index.md to get started.
 ---
 
-# ${config.site.name || "Welcome"}
+# Welcome
 
-This is your starter page. Replace this content with your own
-markdown — every \`.md\` file under \`content/\` becomes a page.
+This is the starting point of ${siteName}, built with
+[Dogsbay](https://github.com/dogsbay/dogsbay). Replace this
+content with your own — every \`.md\` file under \`content/\` becomes
+a page.
 
-## What's next
+> [!TIP]
+> Edit this file (\`content/index.md\`) and save. The dev server
+> reloads automatically.
 
-- Edit this file (\`content/index.md\`) to change the home page.
-- Add more \`.md\` files alongside it for additional pages.
-- Run \`dogsbay site dev\` to preview live as you edit.
-- See \`dogsbay.config.yml\` for site-wide settings (theme, agent
-  readiness, deploy target, etc.).
+## Get started in 60 seconds
 
-For the full reference, see https://github.com/dogsbay/dogsbay.
+:::steps
+1. **Edit a page**
+   Open \`content/index.md\` and change something. Save — the
+   preview updates live.
+
+2. **Add a page**
+   Create \`content/about.md\` with frontmatter and a heading.
+
+3. **Wire it in**
+   Add the new page to \`content/nav.yml\` so it shows up in the
+   sidebar.
+:::
+
+## Where to go next
+
+:::cards
+- **[Getting started](${basePath}/getting-started)** {icon="rocket"}
+  Three-minute orientation to editing, adding, and grouping pages.
+
+- **[Configuration](${basePath}/getting-started)** {icon="settings"}
+  Site name, theme, base path, and per-source settings live in
+  \`dogsbay.config.yml\`.
+
+- **[Source on GitHub](https://github.com/dogsbay/dogsbay)** {icon="github"}
+  Star, browse, file an issue, or follow the roadmap.
+
+- **[Plugins](https://github.com/dogsbay/dogsbay/tree/main/docs)** {icon="puzzle"}
+  Image zoom, TypeDoc, and your own — the plugin API is small,
+  typed, and explicit.
+:::
+
+## Markdown that does more
+
+Cards, steps, tabs, callouts, fenced code — Dogsbay markdown is
+a small superset of CommonMark with directives for the components
+docs sites need most. Here's the same config in two formats:
+
+:::tabs
+YAML
+:   \`\`\`yaml
+    site:
+      name: ${siteName.includes("documentation") ? "Acme Docs" : siteName}
+      url: https://example.com
+    content:
+      sources:
+        - path: ./content
+          from: dogsbay-md
+    \`\`\`
+
+JSON
+:   \`\`\`json
+    {
+      "site": { "name": "${siteName.includes("documentation") ? "Acme Docs" : siteName}" },
+      "content": {
+        "sources": [{ "path": "./content", "from": "dogsbay-md" }]
+      }
+    }
+    \`\`\`
+:::
+
+For the full markdown reference, see
+[github.com/dogsbay/dogsbay](https://github.com/dogsbay/dogsbay).
+`);
+    written.push(indexPath);
+    const gettingStartedPath = join(contentDir, "getting-started.md");
+    writeFileSync(gettingStartedPath, `---
+title: Getting started
+description: Quick orientation for new contributors.
+---
+
+# Getting started
+
+Three minutes to your first edit. Powered by
+[Dogsbay](https://github.com/dogsbay/dogsbay).
+
+## 1. Edit a page
+
+Open \`content/index.md\` in your editor and change something.
+Save — the dev server reloads automatically.
+
+## 2. Add a page
+
+Create a new file like \`content/about.md\`:
+
+\`\`\`md
+---
+title: About
+---
+
+# About
+
+Whatever you want to say here.
+\`\`\`
+
+Then add it to \`content/nav.yml\` so it appears in the sidebar.
+Each entry is a single-key map — key = label, value = file path:
+
+\`\`\`yaml
+- About: about.md
+\`\`\`
+
+External URLs work the same way:
+
+\`\`\`yaml
+- GitHub: https://github.com/your-org/your-repo
+\`\`\`
+
+## 3. Group pages
+
+To create a section in the sidebar, give the entry a list of
+children instead of a single file:
+
+\`\`\`yaml
+- Guides:
+    - Configuration: guides/configuration.md
+    - Deployment: guides/deployment.md
+\`\`\`
+
+The folder structure under \`content/\` doesn't have to match the
+nav — but it usually does, because it makes URLs predictable.
+`);
+    written.push(gettingStartedPath);
+    const navPath = join(contentDir, "nav.yml");
+    writeFileSync(navPath, `# Sidebar navigation. Loaded by Dogsbay automatically — name this
+# file nav.yml, nav.yaml, or nav.json (in that order of precedence).
+#
+# Each entry is a single-key map. The key is the sidebar label.
+# The value is one of:
+#   - a file path (relative to content/, e.g. "guide.md")
+#   - an absolute URL (e.g. "https://...")
+#   - a list of child entries (creates a group)
+#
+# Examples:
+#   - Home: index.md                       # leaf — file path
+#   - GitHub: https://github.com/…         # leaf — external URL
+#   - Guides:                              # group — children below
+#       - Configuration: guides/config.md
+#       - Deployment: guides/deploy.md
+#
+# Edit freely as you add or rearrange pages. See
+# https://github.com/dogsbay/dogsbay for the full nav-file reference.
+
+- Home: index.md
+- Getting started: getting-started.md
 `);
-    return indexPath;
+    written.push(navPath);
+    return written;
 }
 // ─── Resolution: flags + prompts → DogsbayConfig ─────────────────────────
 async function resolveConfig(opts, interactive) {
@@ -168,10 +321,15 @@ function resolveNonInteractive(opts) {
     if (!opts.siteName?.trim()) {
         throw new Error("--site-name is required when running non-interactively (no TTY or --yes).");
     }
-    if (!opts.content?.trim()) {
-        throw new Error("--content is required when running non-interactively (no TTY or --yes).");
-    }
-    return applyDefaults(buildConfig(opts));
+    // Default --content to ./content (matches the interactive default
+    // and the convention every other Dogsbay command assumes). This
+    // makes `dogsbay site init <dir> --yes --site-name X` Just Work
+    // without forcing the writer to remember a redundant flag.
+    const resolved = {
+        ...opts,
+        content: opts.content?.trim() || "./content",
+    };
+    return applyDefaults(buildConfig(resolved));
 }
 async function resolveInteractive(opts) {
     const answers = await prompts([
@@ -378,6 +536,9 @@ function buildConfig(opts) {
     if (opts.deploy === "cloudflare-workers") {
         config.deploy = { target: "cloudflare-workers" };
     }
+    else if (opts.deploy === "github-pages") {
+        config.deploy = { target: "github-pages" };
+    }
     if (opts.plausibleDomain?.trim()) {
         config.analytics = {
             plausible: {
@@ -401,14 +562,14 @@ function findExistingConfig(dir) {
     }
     return null;
 }
-function printNextSteps(absTarget, outputDir, config, starterContentPath) {
+function printNextSteps(absTarget, outputDir, config, starterContentPaths) {
     void config;
     const sameDir = absTarget === outputDir;
     console.log("");
     console.log(pc.green("Wrote:"));
     console.log(`  ${absTarget}/dogsbay.config.yml`);
-    if (starterContentPath) {
-        console.log(`  ${starterContentPath}`);
+    for (const p of starterContentPaths) {
+        console.log(`  ${p}`);
     }
     console.log(`  ${outputDir}/package.json`);
     console.log(`  ${outputDir}/astro.config.mjs`);

package/dist/config/defaults.js

@@ -73,10 +73,17 @@ export function applyDefaults(config) {
 function fillTaxonomyDefaults(raw) {
     const out = {};
     for (const [name, entry] of Object.entries(raw)) {
+        // Declaring `prefixes:` (with their own labels / colors) is a strong
+        // signal the writer wants `/tags/<prefix>/` to be a real browsable
+        // index — not just a styling axis. Default `hierarchical` to true
+        // in that case so prefix-index routes get emitted and the
+        // breadcrumb / sub-tag links don't 404. Writers can opt out with
+        // `hierarchical: false` explicitly.
+        const hasPrefixes = entry.prefixes !== undefined && Object.keys(entry.prefixes).length > 0;
         out[name] = {
             indexPath: entry.indexPath ?? `/${name}`,
             values: entry.values,
-            hierarchical: entry.hierarchical ?? false,
+            hierarchical: entry.hierarchical ?? hasPrefixes,
             prefixes: entry.prefixes,
             labels: entry.labels,
         };

package/dist/config/load.js

@@ -260,38 +260,12 @@ function validateSite(site, sourcePath) {
                 `or repeated slashes. Got ${JSON.stringify(s.basePath)}`);
         }
     }
-    // Cross-field check: site.url must be host-only (no path) when
-    // a non-empty basePath is set. Astro itself splits these as
-    // `site` (origin) + `base` (path); double-counting the prefix
-    // produces canonical URLs like https://example.com/docs/docs/.
-    // Detect by parsing site.url as a URL and rejecting any non-`/`
-    // pathname when basePath is configured.
-    if (typeof s.url === "string" && s.url.length > 0) {
-        let parsedUrl;
-        try {
-            parsedUrl = new URL(s.url);
-        }
-        catch {
-            // Invalid URL — leave further checks for downstream Astro;
-            // we only want to catch the host+path overlap here.
-        }
-        const basePath = typeof s.basePath === "string" ? s.basePath : undefined;
-        const basePathIsSet = basePath !== undefined && basePath !== "" && basePath !== "/";
-        if (parsedUrl && basePathIsSet) {
-            const urlPath = parsedUrl.pathname.replace(/\/+$/, ""); // strip trailing /
-            if (urlPath !== "" && urlPath !== "/") {
-                const origin = `${parsedUrl.protocol}//${parsedUrl.host}`;
-                throw new Error(`site.url must be host-only when site.basePath is set in ${sourcePath}; ` +
-                    `got ${JSON.stringify(s.url)}, expected ${JSON.stringify(origin)} ` +
-                    `with basePath ${JSON.stringify(basePath)}.\n\n` +
-                    `Astro splits these into:\n` +
-                    `  site: ${JSON.stringify(origin)}\n` +
-                    `  base: ${JSON.stringify(basePath)}\n` +
-                    `Without this fix, canonical URLs double-count the prefix ` +
-                    `(e.g. ${origin}${urlPath}${basePath}/).`);
-            }
-        }
-    }
+    // site.url and site.basePath are now independent prefixes that
+    // compose at emit time. The path component of site.url drives
+    // Astro's `base` (where the served space sits in the host);
+    // basePath stays as content's filesystem position within that
+    // served space. See plans/astro-base-from-site-url.md and
+    // packages/format-astro/src/base-path.ts:resolvePrefixes.
     return s;
 }
 const VALID_FROM = [

package/dist/config/to-astro-options.js

@@ -22,6 +22,7 @@ export function configToAstroOptions(config) {
         plausibleDomain: config.analytics?.plausible?.domain,
         plausibleScriptUrl: config.analytics?.plausible?.scriptUrl,
         deploy: config.deploy?.target,
+        inlineStylesheets: config.build?.inlineStylesheets,
         llmsTxt: config.agent?.llmsTxt,
         mdMirror: config.agent?.mdMirror,
         aiTrain: config.agent?.contentSignal?.aiTrain,

package/dist/import-content.js

@@ -1,4 +1,4 @@
-import { normalizeBasePath } from "@dogsbay/format-astro";
+import { normalizeBasePath, resolvePrefixes } from "@dogsbay/format-astro";
 import { plugin as mkdocsPlugin } from "@dogsbay/format-mkdocs/cli";
 import { plugin as astroPlugin } from "@dogsbay/format-astro/cli";
 import { plugin as obsidianPlugin } from "@dogsbay/format-obsidian/cli";
@@ -396,16 +396,17 @@ function buildImportOptions(config, source) {
     if (config.taxonomies) {
         opts.taxonomyNames = Object.keys(config.taxonomies);
     }
-    // Pass site.basePath through as `hrefPrefix` so nav-builders
-    // produce hrefs matching where pages will actually be emitted.
-    // `normalizeBasePath(undefined)` returns the platform default
-    // (`/docs`) so we ALWAYS thread a value — leaving it unset would
-    // force every importer to invent its own fallback (which they did,
-    // inconsistently). Importers that care about basePath are free to
-    // ignore it, but the default makes "namespace-prefixed nav builds
-    // correctly" the path of least resistance. See
-    // plans/configurable-base-path.md and the api-docs example in
-    // plans/openapi-builtin.md.
-    opts.hrefPrefix = normalizeBasePath(config.site.basePath);
+    // Pass the COMBINED URL prefix (urlBase from site.url's path +
+    // site.basePath) as `hrefPrefix` so nav-builders produce hrefs
+    // matching the served URL of each page. Two prefix layers
+    // because subpath-mounted deploys (GH Pages project pages,
+    // multi-mount Cloudflare under one Worker) add a host-level
+    // prefix on top of dogsbay's basePath. See
+    // plans/astro-base-from-site-url.md.
+    //
+    // Back-compat: when site.url is origin-only (no path), urlBase
+    // is empty and combined === basePath, so existing sites see no
+    // change.
+    opts.hrefPrefix = resolvePrefixes(config.site.url, config.site.basePath).combined;
     return opts;
 }