dogsbay 0.2.0-beta.39 → 0.2.0-beta.40

package/dist/commands/migrate-mkdocs.js

@@ -99,7 +99,7 @@ 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);
+    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config, { inlineAutodoc: options.inlineAutodoc ?? false });
     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).
@@ -120,6 +120,12 @@ export async function migrateMkdocs(source, options) {
     if (assetCount > 0) {
         console.log(pc.green(`Copied`) + ` ${assetCount} asset files to content/_assets/`);
     }
+    // 4b. Collect extra_css from mkdocs.yml. Paths are relative to
+    //     docs_dir (MkDocs convention). emitSiteScaffold below
+    //     copies the files to astro/src/styles/custom/ AND appends
+    //     `@import "./custom/<file>";` to global.css so they load on
+    //     every page.
+    const extraCss = extractExtraCssRel(config, fullDocsDir);
     // 5. Build dogsbay.config.yml. agent.{llmsTxt, mdMirror} default
     //    to true in config/defaults.ts — listing them explicitly
     //    makes the migrated config self-documenting. NO `output:`
@@ -159,7 +165,16 @@ export async function migrateMkdocs(source, options) {
         llmsTxt: true,
         mdMirror: true,
         local: options.local,
+        // Extra CSS from the source mkdocs.yml. emitSiteScaffold
+        // copies the files into astro/src/styles/custom/ and
+        // appends imports to global.css so they apply site-wide.
+        extraCss,
+        sourceDir: fullDocsDir,
     }, true);
+    if (extraCss.length > 0) {
+        console.log(pc.green(`Copied`) +
+            ` ${extraCss.length} extra_css file(s) to astro/src/styles/custom/`);
+    }
     console.log(pc.green(`Scaffolded`) + ` Astro project at ./astro/ (theme, components, package.json)`);
     // 7. MIGRATION.md — humans-only summary of the conversion.
     //    Captures lossy items the parser flagged so the user can
@@ -186,7 +201,7 @@ export async function migrateMkdocs(source, options) {
         console.log("Review MIGRATION.md for what survived and what didn't.");
     }
 }
-async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsConfig) {
+async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsConfig, opts) {
     // Dynamic imports for the parser + serializer — same pattern
     // used in import-mkdocs to avoid pulling these into the CLI's
     // type-checking graph (they're workspace deps, not direct).
@@ -206,6 +221,11 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
     // mapping form — without that tolerance PyMdownX Blocks like
     // `/// note` fall through to raw paragraphs in the output).
     const detected = configureFromMkdocs(mkdocsConfig.markdown_extensions);
+    // Extract macros include_yaml + autodoc paths from mkdocs.yml so
+    // the parser expands them at migration time. Native Dogsbay-MD
+    // templating + includes are deferred — see
+    // plans/dogsbay-md-templating.md.
+    const macrosData = extractMacrosData(mkdocsConfig, sourceDir);
     md.use(mkdocsPlugin, {
         ...detected,
         snippets: {
@@ -220,21 +240,52 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
         // See packages/cli/skills/platform/migration-shape/SKILL.md
         // → "Internal links — root-relative absolute slugs".
         linkRewrite: { baseUrl: "" },
+        // fileInclude: `{* ../../docs_src/foo.py *}` in MkDocs sources
+        // resolves relative to the mkdocs project root (where
+        // mkdocs.yml lives). Setting docsDir = sourceDir makes
+        // resolve() walk paths from the project root.
+        fileInclude: { root: sourceDir, docsDir: sourceDir },
+        // variants: auto-generate `//// tab` blocks from sibling files
+        // (foo.md + foo_py310.md → tabs with "Python 3.10+" / current).
+        // Pointed at the actual docs_dir so the sibling walk reads the
+        // right tree.
+        variants: { docsDir: fullDocsDir },
+        // templates (mkdocs-macros plugin): Jinja2/nunjucks expressions
+        // like `{{ contributors }}` / `{% for %}`. The parser reads
+        // the YAMLs at parse time, expands the templates, and the
+        // output is plain Dogsbay-MD prose.
+        ...(macrosData ? { templates: { dataFiles: macrosData } } : {}),
     });
-    // Auto-detect mkdocstrings sourceRoot. Phase 3 default = inline,
-    // so the autodoc pipeline runs at migration time. The resolved
-    // api-* TreeNodes serialize through Dogsbay-MD's `renderUnknown`
-    // (HTML fallback) — known limitation; first-class api-*
-    // serialization lands with Phase 4.
-    const autodocSourceRoot = detectAutodocSourceRoot(sourceDir, mkdocsConfig);
+    // Auto-detect mkdocstrings sourceRoot. Phase 4 default = preserve:
+    // `:::` directives stay as paragraph text after parse, then a
+    // post-walk converts them to Dogsbay-MD `autodoc-ref` TreeNodes
+    // which serialize as `:::autodoc{ref="..."}`. site-build resolves
+    // them on every build via @dogsbay/autodoc-python — Python signature
+    // changes propagate without a re-migration. The `--inline-autodoc`
+    // flag opts into the older snapshot behaviour (autodoc resolved at
+    // migration time, written as `:::api-*` directives).
+    const autodocSourceRootAbs = detectAutodocSourceRoot(sourceDir, mkdocsConfig);
+    // For the directive form we store the sourceRoot RELATIVE to the
+    // migrated site's config dir (= outputDir). That way the directives
+    // survive moving the migrated project around the filesystem; site
+    // build resolves them against the config location.
+    const autodocSourceRootRel = autodocSourceRootAbs
+        ? toRelativeFromConfig(autodocSourceRootAbs, outputDir)
+        : null;
     const parseOpts = {
         collapse: false,
         youtubeEmbed: true,
         diagrams: true,
     };
-    if (autodocSourceRoot) {
-        parseOpts.autodoc = { sourceRoot: autodocSourceRoot };
+    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 };
     }
+    // Preserve mode (default): no `autodoc` in parseOpts. The `:::`
+    // paragraphs stay as raw text; we walk them in post-process and
+    // convert to autodoc-ref TreeNodes.
     const mdFiles = findMarkdownFiles(fullDocsDir);
     const lossy = [];
     let pageCount = 0;
@@ -248,6 +299,14 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
                 ...parseOpts,
                 env: { filePath: relPath },
             });
+            // Preserve mode (default): convert any mkdocstrings `:::` text
+            // paragraphs in the parsed tree to Dogsbay-MD `autodoc-ref`
+            // TreeNodes. The serializer emits these as `:::autodoc{...}`
+            // directives; site-build resolves them on every build. Skipped
+            // when --inline-autodoc resolved them at parse time already.
+            if (!opts.inlineAutodoc && autodocSourceRootRel) {
+                rewriteMkdocstringsDirectivesToAutodocRefs(tree, autodocSourceRootRel);
+            }
             // Rewrite image references to /_assets/<rel>/... canonical
             // form. format-mkdocs's linkRewrite (configured above) already
             // resolved relative paths to root-relative `/img/...` form;
@@ -264,16 +323,21 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
             // anyway — no behavioural difference.
             const body = treeToDogsbayMd(tree);
             writeFileSync(destPath, body.endsWith("\n") ? body : body + "\n");
-            // Flag the autodoc HTML-fallback case so MIGRATION.md can
-            // call it out per-file. Detect by scanning the source for
-            // mkdocstrings directives — if any were resolved at parse
-            // time, the page contains snapshotted api-* HTML.
+            // Note pages with mkdocstrings directives in MIGRATION.md.
+            // Default mode emits :::autodoc directives that site-build
+            // resolves on every build (live). --inline-autodoc snapshots
+            // at migration time (frozen).
             if (/^:::\s+\S/m.test(source)) {
                 lossy.push({
                     file: relPath,
-                    reason: "Contains mkdocstrings ::: directives. Resolved to a snapshot at " +
-                        "migration time; renders as raw HTML until Phase 4 adds a " +
-                        "first-class :::autodoc directive to Dogsbay-MD.",
+                    reason: opts.inlineAutodoc
+                        ? "Contains mkdocstrings ::: directives. --inline-autodoc " +
+                            "resolved them to a snapshot at migration time — Python " +
+                            "signature changes will NOT propagate until you re-migrate."
+                        : "Contains mkdocstrings ::: directives. Converted to " +
+                            ":::autodoc{ref=\"...\"} directives. site-build resolves " +
+                            "them on every build via @dogsbay/autodoc-python — Python " +
+                            "signature changes propagate automatically.",
                 });
             }
             pageCount++;
@@ -288,27 +352,162 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
     }
     return { pageCount, lossy };
 }
+/**
+ * Auto-detect the Python source root for mkdocstrings autodoc.
+ *
+ * mkdocs.yml's `plugins:` can be either a list (canonical) or a
+ * mapping (FastAPI-style) — `mkdocstrings` is the key in both. We
+ * extract its config and walk:
+ *
+ *   1. mkdocstrings.handlers.python.paths (explicit declaration)
+ *   2. mkdocstrings.paths (alternate location seen in some sites)
+ *   3. Walk up from sourceDir looking for a directory that contains
+ *      ONE OF: pyproject.toml, setup.py, or a Python package
+ *      matching the autodoc identifiers (e.g. `fastapi/__init__.py`).
+ *      Tops out 4 levels up; if nothing found, returns null and
+ *      the migration warns + skips autodoc.
+ *
+ * Returns null when mkdocstrings isn't declared at all.
+ */
 function detectAutodocSourceRoot(sourceDir, mkdocsConfig) {
-    // mkdocs.yml -> plugins -> mkdocstrings -> handlers -> python ->
-    // paths is the canonical declaration site. We accept either a
-    // string or array and resolve relative to the mkdocs project.
+    const mkdocstrings = extractMkdocstringsConfig(mkdocsConfig);
+    if (!mkdocstrings)
+        return null;
+    // Explicit `paths:` declaration.
+    const explicit = mkdocstrings.handlers?.python?.paths ?? mkdocstrings.paths;
+    if (typeof explicit === "string")
+        return resolve(sourceDir, explicit);
+    if (Array.isArray(explicit) && typeof explicit[0] === "string") {
+        return resolve(sourceDir, explicit[0]);
+    }
+    // Walk up looking for a Python project marker. FastAPI's layout
+    // puts mkdocs.yml at docs/en/mkdocs.yml and the package at
+    // ../../fastapi/, so we check up to 4 levels.
+    let dir = sourceDir;
+    for (let i = 0; i < 4; i++) {
+        if (existsSync(join(dir, "pyproject.toml")) ||
+            existsSync(join(dir, "setup.py"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Pull the `mkdocstrings:` block out of mkdocs.yml's plugins field,
+ * which can be either a list-of-entries or a mapping. Returns
+ * null if mkdocstrings isn't declared.
+ */
+function extractMkdocstringsConfig(mkdocsConfig) {
     const plugins = mkdocsConfig.plugins;
-    if (!Array.isArray(plugins))
+    if (Array.isArray(plugins)) {
+        for (const entry of plugins) {
+            if (typeof entry === "string" && entry === "mkdocstrings")
+                return {};
+            if (entry && typeof entry === "object" && "mkdocstrings" in entry) {
+                const value = entry.mkdocstrings;
+                if (value && typeof value === "object") {
+                    return value;
+                }
+                return {};
+            }
+        }
+        return null;
+    }
+    if (plugins && typeof plugins === "object") {
+        // Mapping form (FastAPI uses this).
+        const map = plugins;
+        if (!("mkdocstrings" in map))
+            return null;
+        const value = map.mkdocstrings;
+        if (value && typeof value === "object")
+            return value;
+        return {};
+    }
+    return null;
+}
+/**
+ * Extract macros plugin data file mappings from mkdocs.yml.
+ * Returns { varName: absolutePath } for each `include_yaml` entry,
+ * or null if the macros plugin isn't configured.
+ *
+ * Mirrors import-mkdocs's extractMacrosData. The `plugins:` block
+ * can be either a list (canonical) or a mapping (FastAPI-style);
+ * accept both. The include_yaml entries are themselves a list of
+ * single-key maps:
+ *
+ *   plugins:
+ *     macros:
+ *       include_yaml:
+ *         - github_sponsors: ../en/data/github_sponsors.yml
+ *         - people: ../en/data/people.yml
+ */
+function extractMacrosData(mkdocsConfig, sourceDir) {
+    const plugins = mkdocsConfig.plugins;
+    if (!plugins)
+        return null;
+    let macrosConfig = null;
+    if (Array.isArray(plugins)) {
+        for (const p of plugins) {
+            if (typeof p === "object" && p !== null && "macros" in p) {
+                macrosConfig = p.macros;
+                break;
+            }
+            if (p === "macros") {
+                macrosConfig = {};
+                break;
+            }
+        }
+    }
+    else if (typeof plugins === "object") {
+        if ("macros" in plugins) {
+            macrosConfig =
+                plugins.macros || {};
+        }
+    }
+    if (!macrosConfig)
+        return null;
+    const includeYaml = macrosConfig.include_yaml;
+    if (!includeYaml || !Array.isArray(includeYaml))
         return null;
-    for (const entry of plugins) {
-        if (entry && typeof entry === "object" && "mkdocstrings" in entry) {
-            const handlers = entry.mkdocstrings?.handlers;
-            const paths = handlers?.python?.paths;
-            if (typeof paths === "string")
-                return resolve(sourceDir, paths);
-            if (Array.isArray(paths) && typeof paths[0] === "string") {
-                return resolve(sourceDir, paths[0]);
+    const result = {};
+    for (const entry of includeYaml) {
+        if (typeof entry === "string") {
+            const name = entry.replace(/\.[^.]+$/, "").split("/").pop() || entry;
+            result[name] = resolve(sourceDir, entry);
+        }
+        else if (typeof entry === "object" && entry !== null) {
+            const [name, path] = Object.entries(entry)[0];
+            if (typeof path === "string") {
+                result[name] = resolve(sourceDir, path);
             }
         }
     }
-    // Fallback: many mkdocstrings users keep Python source at the
-    // project root next to mkdocs.yml.
-    return sourceDir;
+    return Object.keys(result).length > 0 ? result : null;
+}
+/**
+ * Read mkdocs.yml's `extra_css:` list — returns paths verbatim
+ * (relative to docs_dir, the MkDocs convention) for the entries
+ * whose files exist on disk. The list is passed through to
+ * emitSiteScaffold's `extraCss` + `sourceDir` options, which
+ * copies the files into astro/src/styles/custom/ and appends
+ * `@import` statements to the generated global.css.
+ */
+function extractExtraCssRel(mkdocsConfig, fullDocsDir) {
+    const raw = mkdocsConfig.extra_css;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            continue;
+        if (existsSync(resolve(fullDocsDir, entry)))
+            out.push(entry);
+    }
+    return out;
 }
 function findMarkdownFiles(dir) {
     const results = [];
@@ -390,6 +589,108 @@ export function rewriteAssetHref(src) {
     const trimmed = src.replace(/^\/+/, "").replace(/^\.\/+/, "");
     return `/_assets/${posix.normalize(trimmed)}`;
 }
+// ── mkdocstrings ::: → :::autodoc{ref="..."} (preserve mode) ──
+/**
+ * After parseMkdocsMarkdown returns (without the autodoc option),
+ * `::: identifier` directives appear as paragraph nodes whose first
+ * prose child's html starts with `:::` text. Walk the tree, find
+ * them, and replace each with an autodoc-ref TreeNode that
+ * serializes to a Dogsbay-MD `:::autodoc{ref="..."}` directive.
+ *
+ * Site-build later resolves these via @dogsbay/autodoc-python on
+ * every build, so the rendered API ref stays in sync with the
+ * Python source.
+ *
+ * The mkdocstrings YAML option block (indented after the directive)
+ * is parsed and merged into the autodoc-ref props.
+ */
+function rewriteMkdocstringsDirectivesToAutodocRefs(nodes, sourceRootRel) {
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (node.type === "paragraph" && node.children) {
+            const proseChild = node.children.find((c) => c.type === "prose" && typeof c.html === "string" && c.html);
+            if (proseChild?.html) {
+                const directive = parseMkdocstringsDirective(proseChild.html.trim());
+                if (directive) {
+                    nodes[i] = {
+                        type: "autodoc-ref",
+                        props: {
+                            ref: directive.ref,
+                            sourceRoot: sourceRootRel,
+                            ...directive.options,
+                        },
+                    };
+                    continue;
+                }
+            }
+        }
+        if (node.children) {
+            rewriteMkdocstringsDirectivesToAutodocRefs(node.children, sourceRootRel);
+        }
+    }
+}
+const MKDOCSTRINGS_FIRST_LINE_RE = /^:::\s+(\S+)\s*$/;
+/**
+ * Parse the mkdocstrings directive text (`::: identifier` +
+ * optional indented YAML body). Returns null if the text doesn't
+ * look like a directive.
+ *
+ *   ::: fastapi.FastAPI
+ *       options:
+ *         show_source: true
+ *         members:
+ *           - get
+ *           - post
+ *
+ * Becomes:
+ *
+ *   { ref: "fastapi.FastAPI",
+ *     options: { showSource: true, members: ["get", "post"] } }
+ *
+ * The handler-options snake_case → camelCase mapping mirrors the
+ * one in @dogsbay/format-mkdocs's loader so the autodoc engine
+ * receives the same keys regardless of mode (preserve vs inline).
+ */
+function parseMkdocstringsDirective(text) {
+    const firstLine = text.split("\n")[0].trim();
+    const match = MKDOCSTRINGS_FIRST_LINE_RE.exec(firstLine);
+    if (!match)
+        return null;
+    const ref = match[1];
+    const remainder = text.split("\n").slice(1).join("\n").trim();
+    const options = {};
+    if (remainder) {
+        try {
+            const parsed = YAML.parse(remainder);
+            if (parsed && typeof parsed === "object" && parsed.options) {
+                for (const [snake, value] of Object.entries(parsed.options)) {
+                    options[snakeToCamel(snake)] = value;
+                }
+            }
+        }
+        catch {
+            // Malformed YAML — drop the options, keep the directive
+            // pointing at the bare ref. Better than failing the whole
+            // page migration.
+        }
+    }
+    return { ref, options };
+}
+function snakeToCamel(s) {
+    return s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Compute the sourceRoot to bake into `:::autodoc{sourceRoot="..."}`
+ * directives. The migrated site lives at `outputDir`; we want a
+ * path relative to that so the directives travel with the site if
+ * it's moved.
+ */
+function toRelativeFromConfig(absSourcePath, outputDir) {
+    const rel = relative(outputDir, absSourcePath);
+    // Ensure forward slashes in the emitted string regardless of
+    // platform — the directives are read by site-build cross-platform.
+    return rel.split(/[\\/]/).join("/") || ".";
+}
 function copyAssets(srcDocsDir, destPublicDir) {
     const exts = new Set([
         ".png",

package/dist/commands/site-build.js

@@ -165,6 +165,28 @@ export async function siteBuild(cwd, options) {
     if (resolvedPlugins.some((p) => p.plugin.transformNav)) {
         nav = await runTransformNav(resolvedPlugins, baseCtx, nav);
     }
+    // 7c.5. Resolve :::autodoc directives — Phase 4 of
+    // plans/mkdocs-import-architecture.md. Walk every page tree for
+    // `autodoc-ref` placeholders left by format-dogsbay-md's parser,
+    // call @dogsbay/autodoc-python (resolveIdentifier + symbolToTreeNode),
+    // and splice the rendered api-* tree in place. Failures log a
+    // warning and leave the placeholder intact (its fallback body
+    // renders). Done BEFORE strict ref validation (7d) so structural
+    // checks see the resolved tree, not the placeholder.
+    const { resolveAutodocRefs } = await import("../resolve-autodoc.js");
+    const autodocResult = await resolveAutodocRefs(pages, {
+        configDir: dirname(configPath),
+    });
+    if (autodocResult.resolved > 0 || autodocResult.failed > 0) {
+        const parts = [];
+        if (autodocResult.resolved > 0) {
+            parts.push(`${autodocResult.resolved} resolved`);
+        }
+        if (autodocResult.failed > 0) {
+            parts.push(`${autodocResult.failed} failed`);
+        }
+        console.log(`  Autodoc: ${parts.join(", ")}`);
+    }
     console.log(`  Imported ${pages.length} pages from ${importer.name}` +
         (draftCount > 0 && !options.includeDrafts
             ? ` (${draftCount} draft${draftCount === 1 ? "" : "s"} excluded)`

package/dist/index.js

@@ -184,6 +184,9 @@ 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("--inline-autodoc", "Resolve mkdocstrings ::: directives at migration time (snapshot). " +
+    "Default is :::autodoc directives that site-build resolves on " +
+    "every build (live re-rendering).")
     .option("--local", "Use file: references to local monorepo packages (for development)")
     .action((source, options) => migrateMkdocs(source, options));
 program

package/dist/resolve-autodoc.js

@@ -0,0 +1,218 @@
+/**
+ * Build-time resolver for the `:::autodoc` directive.
+ *
+ * Phase 4 of plans/mkdocs-import-architecture.md.
+ *
+ * format-dogsbay-md parses `:::autodoc{ref="..."}` blocks into
+ * `autodoc-ref` TreeNode placeholders. site-build calls
+ * `resolveAutodocRefs` between the importer's content load and
+ * format-astro's emission to substitute the placeholders with
+ * rendered api-* TreeNodes (api-class, api-member, api-doc, etc.).
+ *
+ * Resolution flow per ref:
+ *   1. Read `ref` + `sourceRoot` (+ render options) from props.
+ *   2. Call @dogsbay/autodoc-python.resolveIdentifier → SymbolInfo.
+ *   3. Call symbolToTreeNode → TreeNode.
+ *   4. Replace the autodoc-ref node in the page tree.
+ *
+ * Failures (missing source, unresolvable identifier, parse error)
+ * leave the autodoc-ref node intact and log a warning. The
+ * directive's fallback body (if any) renders in its place.
+ */
+import { resolve as resolvePath } from "node:path";
+import MarkdownIt from "markdown-it";
+import pc from "picocolors";
+import { resolveIdentifier, symbolToTreeNode, } from "@dogsbay/autodoc-python";
+/**
+ * Default render options for autodoc directives. Mirrors
+ * mkdocstrings' Python handler defaults — these are the same
+ * values format-mkdocs/src/loader.ts baked in during the legacy
+ * import flow, kept here so migrate-mkdocs + site-build produce
+ * output that matches the legacy import path by default. A
+ * directive's own props override any default it doesn't like
+ * (e.g. `showSource: false` to skip the collapsible source).
+ */
+const AUTODOC_RENDER_DEFAULTS = {
+    showRootHeading: false,
+    showRootFullPath: true,
+    showIfNoDocstring: false,
+    showBases: true,
+    showSource: true,
+    showSignature: true,
+    mergeInitIntoClass: false,
+    separateSignature: false,
+    unwrapAnnotated: false,
+    groupByCategory: true,
+    inheritedMembers: false,
+    filters: ["!^_[^_]"],
+    membersOrder: "alphabetical",
+    headingLevel: 2,
+};
+/**
+ * Lightweight slugifier matching format-mkdocs's behaviour so the
+ * heading slugs we generate here line up with what hrefs against
+ * these symbols expect.
+ */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Walk every page's TreeNode tree and substitute `autodoc-ref`
+ * placeholders with rendered api-* trees.
+ *
+ * Pages are mutated in place — caller owns the array. Returns a
+ * tally of resolved / failed refs for the build log.
+ */
+export async function resolveAutodocRefs(pages, options) {
+    let resolved = 0;
+    let failed = 0;
+    const md = new MarkdownIt({ html: true, linkify: true });
+    for (const page of pages) {
+        await walkAndResolve(page.tree, {
+            configDir: options.configDir,
+            md,
+            onResolved: () => {
+                resolved++;
+            },
+            onFailed: (ref, reason) => {
+                failed++;
+                console.warn(pc.yellow(`  Warning: autodoc ref "${ref}" failed to resolve — ${reason}. ` +
+                    `Page: ${page.slug}`));
+            },
+        });
+        // After substitution, walk the resolved tree and append heading
+        // entries for every api-class / api-member. Without this, the
+        // TOC component only sees the page's prose H1 — the rendered
+        // API ref pages have no method index in the sidebar TOC.
+        //
+        // Mirrors format-mkdocs/src/loader.ts → extractHeadings.
+        if (page.tree.some(treeHasApiHeading)) {
+            appendApiHeadings(page);
+        }
+    }
+    return { resolved, failed };
+}
+/**
+ * True if the subtree carries at least one api-class / api-member —
+ * cheap pre-check before we walk to collect headings.
+ */
+function treeHasApiHeading(node) {
+    if (node.type === "api-class" || node.type === "api-member")
+        return true;
+    if (node.children) {
+        for (const child of node.children) {
+            if (treeHasApiHeading(child))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Walk the page's TreeNode tree for api-class / api-member nodes
+ * and append a Heading entry for each. Depth follows format-
+ * mkdocs's convention: api-class is depth 2 (top-level symbol),
+ * api-member is depth 3 (method / attribute under a class). The
+ * `kind` prop is preserved on the heading so the TOC component
+ * can render type-colored badges (class blue, method green, etc.).
+ *
+ * Slug allocation respects existing entries in page.headings to
+ * avoid collisions with handwritten prose headings.
+ */
+function appendApiHeadings(page) {
+    const seen = new Map();
+    for (const h of page.headings ?? []) {
+        seen.set(h.slug, (seen.get(h.slug) ?? 0) + 1);
+    }
+    const headings = [];
+    function walk(nodes) {
+        for (const node of nodes) {
+            if (node.type === "api-class" || node.type === "api-member") {
+                const name = node.props?.name || "";
+                const kind = node.props?.kind || "";
+                const depth = node.type === "api-class" ? 2 : 3;
+                const baseSlug = slugify(name);
+                const count = seen.get(baseSlug) ?? 0;
+                const slug = count === 0 ? baseSlug : `${baseSlug}-${count}`;
+                seen.set(baseSlug, count + 1);
+                headings.push({ depth, slug, text: name, kind });
+                // Persist the assigned slug on the node so format-astro's
+                // emitter can render the same id on the corresponding
+                // anchor — TOC links and on-page ids stay in sync.
+                if (!node.props)
+                    node.props = {};
+                node.props.slug = slug;
+            }
+            if (node.children)
+                walk(node.children);
+        }
+    }
+    walk(page.tree);
+    if (headings.length > 0) {
+        page.headings = [...(page.headings ?? []), ...headings];
+    }
+}
+async function walkAndResolve(nodes, ctx) {
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (node.type === "autodoc-ref") {
+            const replacement = await resolveOne(node, ctx);
+            if (replacement) {
+                nodes[i] = replacement;
+            }
+            continue;
+        }
+        if (node.children) {
+            await walkAndResolve(node.children, ctx);
+        }
+    }
+}
+async function resolveOne(node, ctx) {
+    const props = (node.props ?? {});
+    const ref = typeof props.ref === "string" ? props.ref : "";
+    const sourceRootRaw = typeof props.sourceRoot === "string" ? props.sourceRoot : "";
+    if (!ref) {
+        ctx.onFailed("(empty)", "no `ref` prop on :::autodoc directive");
+        return null;
+    }
+    if (!sourceRootRaw) {
+        ctx.onFailed(ref, "no `sourceRoot` prop on :::autodoc directive — needed to locate Python source");
+        return null;
+    }
+    // sourceRoot may be a path relative to dogsbay.config.yml.
+    // 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.
+    const renderOptions = {
+        ...AUTODOC_RENDER_DEFAULTS,
+        ...props,
+    };
+    delete renderOptions.ref;
+    delete renderOptions.sourceRoot;
+    try {
+        const symbol = await resolveIdentifier(ref, sourceRoot);
+        if (!symbol) {
+            ctx.onFailed(ref, `identifier not found under ${sourceRoot}`);
+            return null;
+        }
+        const tree = symbolToTreeNode(symbol, renderOptions, ctx.md, ref, sourceRoot);
+        ctx.onResolved();
+        return tree;
+    }
+    catch (err) {
+        ctx.onFailed(ref, err.message);
+        return null;
+    }
+}

package/package.json

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