dogsbay 0.2.0-beta.41 → 0.2.0-beta.43

package/dist/commands/migrate-mkdocs.js

@@ -99,7 +99,15 @@ export async function migrateMkdocs(source, options) {
     //    snippets, macros, autodoc, variants — see @dogsbay/format-
     //    mkdocs's CLAUDE.md) runs identically to import-mkdocs; only
     //    the final write target differs.
-    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config, { inlineAutodoc: options.inlineAutodoc ?? false });
+    // Lift the mkdocstrings Python handler options from mkdocs.yml.
+    // These become the project-level `autodoc.python` config block and
+    // also feed `--inline-autodoc`'s parser globalOptions — see
+    // plans/autodoc-mkdocstrings-options.md.
+    const autodocPythonOptions = extractAutodocOptions(config);
+    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config, {
+        inlineAutodoc: options.inlineAutodoc ?? false,
+        autodocPythonOptions,
+    });
     console.log(pc.green(`Wrote`) + ` ${pageCount} pages to ./content/ as Dogsbay-MD`);
     // 3. Convert MkDocs nav: → ./content/nav.yml in canonical
     //    single-key-map shape (- Label: file.md / nested children).
@@ -131,15 +139,28 @@ export async function migrateMkdocs(source, options) {
     //    makes the migrated config self-documenting. NO `output:`
     //    field — the default (./astro) is what we want; flat layout
     //    (`output: "."`) triggers a rebuild loop in `site dev`.
-    const siteUrl = config.site_url || undefined;
+    // site.url is NOT inherited from the source mkdocs.yml. A
+    // migration almost always moves to a new host, so copying the
+    // source's site_url silently bakes the wrong origin into
+    // robots.txt, sitemap, canonical tags, and llms.txt. The user
+    // supplies the destination explicitly with --site-url; absent,
+    // site.url is left unset and the build emits relative URLs.
+    // sourceSiteUrl is kept only to warn the user it was dropped.
+    const sourceSiteUrl = config.site_url || undefined;
+    const siteUrl = options.siteUrl || undefined;
     const repoUrl = config.repo_url || undefined;
+    // --base-path controls where docs sit under the host. Default
+    // /docs (matches every scaffolded dogsbay site); pass --base-path
+    // "" to serve at the host root — common for a dedicated repo or
+    // GitHub Pages project site.
+    const basePath = options.basePath !== undefined ? options.basePath : "/docs";
     const siteDescription = config.site_description || undefined;
     const dogsbayConfig = {
         schemaVersion: 1,
         site: {
             name: siteName,
             url: siteUrl,
-            basePath: "/docs",
+            basePath,
             description: siteDescription,
             repoUrl,
         },
@@ -150,9 +171,26 @@ export async function migrateMkdocs(source, options) {
             llmsTxt: true,
             mdMirror: true,
         },
+        // Project-level autodoc render options lifted from the source
+        // mkdocs.yml's mkdocstrings handler. resolve-autodoc applies
+        // these under per-directive props so migrated reference pages
+        // render with the same signature/member-order behaviour the
+        // MkDocs site configured. Omitted when the source declared no
+        // renderer-relevant options.
+        ...(autodocPythonOptions
+            ? { autodoc: { python: autodocPythonOptions } }
+            : {}),
     };
     writeFileSync(join(outputDir, "dogsbay.config.yml"), serializeConfig(dogsbayConfig, "yaml"));
     console.log(pc.green(`Wrote`) + ` dogsbay.config.yml`);
+    if (sourceSiteUrl && !siteUrl) {
+        console.log(pc.yellow(`Note:`) +
+            ` source site_url (${sourceSiteUrl}) was not carried over —` +
+            ` a migration moves hosts.`);
+        console.log(`      Set site.url in dogsbay.config.yml (or re-run with` +
+            ` --site-url) so robots.txt,`);
+        console.log(`      sitemap, and llms.txt point at your host.`);
+    }
     // 6. Scaffold the Astro project under ./astro/ (theme,
     //    package.json, astro.config.mjs, tsconfig, copied UI
     //    components). Same emitter `dogsbay site init` uses, just
@@ -160,7 +198,7 @@ export async function migrateMkdocs(source, options) {
     emitSiteScaffold(astroDir, siteName, {
         siteName,
         siteUrl,
-        basePath: "/docs",
+        basePath,
         repoUrl,
         llmsTxt: true,
         mdMirror: true,
@@ -187,6 +225,9 @@ export async function migrateMkdocs(source, options) {
         pageCount,
         assetCount,
         lossy,
+        siteUrl,
+        sourceSiteUrl,
+        basePath,
     }));
     console.log(pc.green(`Wrote`) + ` MIGRATION.md`);
     if (!options.quiet) {
@@ -280,8 +321,16 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
     if (opts.inlineAutodoc && autodocSourceRootAbs) {
         // Snapshot mode: resolve at migration time. The resolved api-*
         // TreeNodes serialize to Dogsbay-MD `:::api-*` directives via
-        // format-dogsbay-md's Phase 4a cases.
-        parseOpts.autodoc = { sourceRoot: autodocSourceRootAbs };
+        // format-dogsbay-md's Phase 4a cases. globalOptions carries the
+        // mkdocstrings handler options so the snapshot matches what the
+        // MkDocs site configured (members_order, merge_init_into_class,
+        // …) rather than the bare mkdocstrings defaults.
+        parseOpts.autodoc = {
+            sourceRoot: autodocSourceRootAbs,
+            ...(opts.autodocPythonOptions
+                ? { globalOptions: opts.autodocPythonOptions }
+                : {}),
+        };
     }
     // Preserve mode (default): no `autodoc` in parseOpts. The `:::`
     // paragraphs stay as raw text; we walk them in post-process and
@@ -429,6 +478,60 @@ function extractMkdocstringsConfig(mkdocsConfig) {
     }
     return null;
 }
+/**
+ * snake_case mkdocstrings handler option → camelCase Dogsbay
+ * `AutodocPythonOptions` key. Options the autodoc renderer doesn't
+ * understand (e.g. `extensions`, `preload_modules`,
+ * `docstring_section_style`) are intentionally absent — they fall
+ * through and are dropped. Mirrors the map in
+ * `format-mkdocs/src/importer.ts` so `migrate-mkdocs` and
+ * `import-mkdocs` honour the same handler options.
+ */
+const MKDOCSTRINGS_OPTION_MAP = {
+    show_source: "showSource",
+    show_bases: "showBases",
+    show_signature: "showSignature",
+    unwrap_annotated: "unwrapAnnotated",
+    group_by_category: "groupByCategory",
+    show_root_full_path: "showRootFullPath",
+    show_root_heading: "showRootHeading",
+    show_if_no_docstring: "showIfNoDocstring",
+    inherited_members: "inheritedMembers",
+    merge_init_into_class: "mergeInitIntoClass",
+    separate_signature: "separateSignature",
+    members_order: "membersOrder",
+    filters: "filters",
+    heading_level: "headingLevel",
+};
+/**
+ * Lift the mkdocstrings Python handler `options:` block out of
+ * mkdocs.yml and map it to `AutodocPythonOptions`.
+ *
+ * A MkDocs site configures the handler once; `import-mkdocs` threads
+ * those options into the autodoc renderer as `globalOptions`. Without
+ * this, migrated `:::autodoc` directives fall back to the bare
+ * mkdocstrings defaults (`merge_init_into_class: false`,
+ * `members_order: alphabetical`) — the reference pages lose the
+ * expanded constructor signature and the document-order member list.
+ *
+ * Returns null when mkdocstrings isn't declared or sets no
+ * renderer-relevant options. See plans/autodoc-mkdocstrings-options.md.
+ */
+function extractAutodocOptions(mkdocsConfig) {
+    const mkdocstrings = extractMkdocstringsConfig(mkdocsConfig);
+    if (!mkdocstrings)
+        return null;
+    const raw = mkdocstrings.handlers?.python?.options;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const src = raw;
+    const out = {};
+    for (const [snake, camel] of Object.entries(MKDOCSTRINGS_OPTION_MAP)) {
+        if (src[snake] !== undefined)
+            out[camel] = src[snake];
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 /**
  * Extract macros plugin data file mappings from mkdocs.yml.
  * Returns { varName: absolutePath } for each `include_yaml` entry,
@@ -785,7 +888,7 @@ function labelFromPath(path) {
 }
 // ── MIGRATION.md ────────────────────────────────────────
 function buildMigrationNotes(args) {
-    const { sourceDir, outputDir, siteName, pageCount, assetCount, lossy } = args;
+    const { sourceDir, outputDir, siteName, pageCount, assetCount, lossy, siteUrl, sourceSiteUrl, basePath, } = args;
     const lines = [
         `# Migration: ${siteName}`,
         "",
@@ -811,19 +914,22 @@ function buildMigrationNotes(args) {
         "npx dogsbay site dev        # watch + preview",
         "```",
         "",
-        "## Re-running the migration",
-        "",
-        "If you find a regression and we ship a fix, re-run with `--force`:",
-        "",
-        "```bash",
-        `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`,
-        "```",
-        "",
-        "Note that `--force` overwrites all generated files; any hand edits",
-        "to `./content/*.md` since the last migration will be lost. Commit",
-        "your work first.",
-        "",
     ];
+    // Site URL section — the destination URL is not inherited from the
+    // source mkdocs.yml, so spell out what was written and what (if
+    // anything) was dropped.
+    lines.push("## Site URL", "");
+    if (siteUrl) {
+        lines.push(`\`site.url\` is set to \`${siteUrl}\` (from \`--site-url\`).`, `\`site.basePath\` is \`${basePath || '""'}\`. robots.txt, the`, "sitemap, canonical tags, and llms.txt all derive from these —", "edit `dogsbay.config.yml` and rebuild to change them.", "");
+    }
+    else {
+        lines.push("`site.url` was left **unset** — a migration moves hosts, so the", "source's `site_url` is intentionally not carried over. The build", "emits relative URLs until you set it.", "");
+        if (sourceSiteUrl) {
+            lines.push(`The source \`mkdocs.yml\` had \`site_url: ${sourceSiteUrl}\` —`, "that points at the *old* host and was dropped on purpose.", "");
+        }
+        lines.push("Set the destination URL in `dogsbay.config.yml`:", "", "```yaml", "site:", "  url: https://you.github.io/your-repo   # drives sitemap, llms.txt, canonical", `  basePath: ${basePath || '""'}`, "```", "", "Or re-run the migration with `--site-url` (and optionally", "`--base-path`).", "");
+    }
+    lines.push("## Re-running the migration", "", "If you find a regression and we ship a fix, re-run with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`, "```", "", "Note that `--force` overwrites all generated files; any hand edits", "to `./content/*.md` since the last migration will be lost. Commit", "your work first.", "");
     if (lossy.length > 0) {
         lines.push("## Known limitations", "");
         lines.push("The following files have content that didn't fully round-trip", "into Dogsbay-MD. Review each one and fix manually:", "");

package/dist/commands/site-build.js

@@ -176,6 +176,10 @@ export async function siteBuild(cwd, options) {
     const { resolveAutodocRefs } = await import("../resolve-autodoc.js");
     const autodocResult = await resolveAutodocRefs(pages, {
         configDir: dirname(configPath),
+        // Project-level autodoc render options (lifted from the source
+        // mkdocs.yml by migrate-mkdocs). Layered under per-directive
+        // props — see plans/autodoc-mkdocstrings-options.md.
+        pythonOptions: config.autodoc?.python,
     });
     if (autodocResult.resolved > 0 || autodocResult.failed > 0) {
         const parts = [];

package/dist/config/load.js

@@ -94,6 +94,7 @@ function validate(parsed, sourcePath) {
         throw new Error(`analytics must be an object in ${sourcePath}`);
     }
     const agent = validateAgent(obj.agent, sourcePath);
+    const autodoc = validateAutodoc(obj.autodoc, sourcePath);
     const taxonomies = validateTaxonomies(obj.taxonomies, sourcePath);
     const propSchema = validatePropSchema(obj.propSchema, sourcePath);
     const plugins = validatePlugins(obj.plugins, sourcePath);
@@ -108,11 +109,66 @@ function validate(parsed, sourcePath) {
         deploy: obj.deploy,
         analytics: obj.analytics,
         agent,
+        autodoc,
         taxonomies,
         propSchema,
         plugins,
     };
 }
+/**
+ * Validate the optional `autodoc:` block. One sub-block per language
+ * handler — only `python` exists today. Field names mirror
+ * `AutodocPythonOptions`; type-checked individually so a typo'd
+ * boolean doesn't silently flip a render default.
+ */
+function validateAutodoc(raw, sourcePath) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error(`autodoc must be an object in ${sourcePath}`);
+    }
+    const a = raw;
+    if (a.python === undefined)
+        return {};
+    if (typeof a.python !== "object" || a.python === null || Array.isArray(a.python)) {
+        throw new Error(`autodoc.python must be an object in ${sourcePath}`);
+    }
+    const p = a.python;
+    const booleanKeys = [
+        "mergeInitIntoClass",
+        "separateSignature",
+        "unwrapAnnotated",
+        "inheritedMembers",
+        "showIfNoDocstring",
+        "showRootHeading",
+        "showRootFullPath",
+        "showBases",
+        "showSource",
+        "showSignature",
+        "groupByCategory",
+    ];
+    for (const key of booleanKeys) {
+        if (p[key] !== undefined && typeof p[key] !== "boolean") {
+            throw new Error(`autodoc.python.${key} must be a boolean in ${sourcePath}`);
+        }
+    }
+    if (p.membersOrder !== undefined &&
+        p.membersOrder !== "source" &&
+        p.membersOrder !== "alphabetical") {
+        throw new Error(`autodoc.python.membersOrder must be "source" or "alphabetical" ` +
+            `in ${sourcePath}; got ${JSON.stringify(p.membersOrder)}`);
+    }
+    if (p.headingLevel !== undefined && typeof p.headingLevel !== "number") {
+        throw new Error(`autodoc.python.headingLevel must be a number in ${sourcePath}`);
+    }
+    if (p.filters !== undefined) {
+        if (!Array.isArray(p.filters) ||
+            p.filters.some((f) => typeof f !== "string")) {
+            throw new Error(`autodoc.python.filters must be an array of strings in ${sourcePath}`);
+        }
+    }
+    return { python: p };
+}
 function validatePlugins(raw, sourcePath) {
     if (raw === undefined)
         return undefined;

package/dist/index.js

@@ -184,6 +184,13 @@ program
     .argument("<source>", "Path to MkDocs project (containing mkdocs.yml)")
     .option("-o, --output <dir>", "Output directory (default: {source}-dogsbay)")
     .option("--force", "Overwrite an existing Dogsbay site at the output dir")
+    .option("--site-url <url>", "Canonical URL of the destination site (e.g. " +
+    "https://you.github.io/repo). Drives robots.txt, sitemap, " +
+    "canonical tags, and llms.txt. NOT inherited from the source " +
+    "mkdocs.yml — a migration moves hosts.")
+    .option("--base-path <path>", 'Path under the host where docs are served (default "/docs"). ' +
+    'Pass --base-path "" to serve at the host root — common for a ' +
+    "dedicated repo / GitHub Pages project site.")
     .option("--inline-autodoc", "Resolve mkdocstrings ::: directives at migration time (snapshot). " +
     "Default is :::autodoc directives that site-build resolves on " +
     "every build (live re-rendering).")

package/dist/resolve-autodoc.js

@@ -75,6 +75,7 @@ export async function resolveAutodocRefs(pages, options) {
     for (const page of pages) {
         await walkAndResolve(page.tree, {
             configDir: options.configDir,
+            pythonOptions: options.pythonOptions,
             md,
             onResolved: () => {
                 resolved++;
@@ -187,16 +188,21 @@ async function resolveOne(node, ctx) {
     // Resolve against configDir so the resolver doesn't depend on
     // process.cwd().
     const sourceRoot = resolvePath(ctx.configDir, sourceRootRaw);
-    // Pull rendering options from props, layered on top of the
-    // mkdocstrings-compatible defaults. tree-builder.ts uses
-    // truthy-checks for several of these (e.g. `if (options.showSource
-    // && symbol.sourceText) { ... }`) — without the defaults the
-    // collapsible source-code block, attribute signatures, and class
-    // bases all silently drop. The defaults mirror format-mkdocs/
-    // src/loader.ts → processAutodocDirectives so the migrated
-    // output matches the legacy import-mkdocs output by default.
+    // Layer rendering options, lowest → highest precedence:
+    //   1. AUTODOC_RENDER_DEFAULTS — bare mkdocstrings defaults.
+    //      tree-builder.ts truthy-checks several of these, so without
+    //      them the collapsible source block, attribute signatures,
+    //      and class bases silently drop.
+    //   2. ctx.pythonOptions — project-level `config.autodoc.python`,
+    //      lifted by migrate-mkdocs from the source mkdocs.yml's
+    //      mkdocstrings handler (members_order, merge_init_into_class,
+    //      …). This is what makes a migrated reference page match the
+    //      original instead of the bare-defaults render.
+    //   3. props — the per-directive `:::autodoc` YAML body, so an
+    //      individual symbol can still override the project default.
     const renderOptions = {
         ...AUTODOC_RENDER_DEFAULTS,
+        ...(ctx.pythonOptions ?? {}),
         ...props,
     };
     delete renderOptions.ref;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.41",
+  "version": "0.2.0-beta.43",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,15 +32,15 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/autodoc-python": "0.2.0-beta.41",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.41",
-    "@dogsbay/format-astro": "0.2.0-beta.41",
-    "@dogsbay/format-obsidian": "0.2.0-beta.41",
-    "@dogsbay/format-mdx": "0.2.0-beta.41",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.41",
-    "@dogsbay/format-starlight": "0.2.0-beta.41",
-    "@dogsbay/format-openapi": "0.2.0-beta.41",
-    "@dogsbay/types": "0.2.0-beta.41"
+    "@dogsbay/autodoc-python": "0.2.0-beta.43",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.43",
+    "@dogsbay/format-astro": "0.2.0-beta.43",
+    "@dogsbay/format-obsidian": "0.2.0-beta.43",
+    "@dogsbay/format-mdx": "0.2.0-beta.43",
+    "@dogsbay/format-starlight": "0.2.0-beta.43",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.43",
+    "@dogsbay/format-openapi": "0.2.0-beta.43",
+    "@dogsbay/types": "0.2.0-beta.43"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",

package/skills/platform/migration-shape/SKILL.md

@@ -62,6 +62,39 @@ This was learned the hard way during Phase 3 of
 emitted `output: "."` and `dogsbay site dev` rebuild-looped on the
 result. The fix was to revert to the standard `output: "./astro"`.
 
+### Destination URL — supplied, not inherited
+
+**Do NOT copy the source format's site URL into `site.url`.** A
+migration almost always moves the docs to a *new* host — GitHub
+Pages, a Cloudflare project, a custom domain. The source's
+`site_url` (MkDocs), `url` (Jekyll `_config.yml`), `baseURL`
+(Hugo), etc. points at the *old* host.
+
+`site.url` feeds `robots.txt`, the sitemap XML, the `Sitemap:` /
+`Llms-Txt:` lines, canonical tags, `llms.txt` absolute URLs, and
+Astro's `site` / `base`. Inheriting the wrong origin silently
+breaks every one of those — and the breakage only shows up after
+a build, in generated files the user doesn't normally read.
+
+**Required:**
+- Migration commands take a `--site-url <url>` flag. Its value
+  goes to `dogsbay.config.yml`'s `site.url` *and* the scaffold
+  emitter's `siteUrl` option. The URL may carry a path component
+  (`https://you.github.io/repo`); `format-astro`'s `parseSiteUrl`
+  splits it into Astro `site` (origin) + `base` (urlBase) — this
+  is exactly how GitHub Pages **project** sites work.
+- Take a `--base-path <path>` flag too. Default `/docs`; `""`
+  serves at the host root. Check `!== undefined` (not truthiness)
+  so the empty string is honoured.
+- When `--site-url` is absent, leave `site.url` **unset** (the
+  build degrades cleanly to relative URLs) — do NOT fall back to
+  the source value.
+- Keep the dropped source URL only to (a) print a one-line note
+  after writing the config and (b) record it in `MIGRATION.md`'s
+  "Site URL" section so the user knows what to set.
+- The *code* repo URL (`repo_url` etc.) **is** inherited — that
+  doesn't change in a docs migration.
+
 ## 2. Asset folder (`content/_assets/`)
 
 All images, diagrams, screenshots, icons, PDFs, and downloadable
@@ -247,6 +280,7 @@ Every migration command MUST have a fixture test asserting all of:
 | `<output>/content/nav.json` does NOT exist | Avoid loader precedence trap |
 | `<output>/dogsbay.config.yml` has `sources: [{ path: ./content, from: dogsbay-md }]` | Config wires content to source |
 | `<output>/dogsbay.config.yml` does NOT set `output:` | Use default `./astro` |
+| `site.url` reflects `--site-url`, NOT the source's URL; absent → unset | Destination URL not inherited |
 | `<output>/astro/package.json` exists | Scaffold under astro/ |
 | `<output>/astro/astro.config.mjs` exists | Scaffold under astro/ |
 | `<output>/astro/src/styles/theme.css` exists | Scaffold under astro/ |