@dogsbay/format-mkdocs 0.2.0-beta.11 → 0.2.0-beta.111

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AAGxE,eAAO,MAAM,MAAM,EAAE,YA+BpB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,gBAAgB,CAAC;AAKtF,eAAO,MAAM,MAAM,EAAE,YA6GpB,CAAC"}

package/dist/cli.js

@@ -1,6 +1,8 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync, copyFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
 import { importMkdocsProject } from "./importer.js";
+import { exportMkdocsProject } from "./export/to-mkdocs-project.js";
+import { formatLedgerReport } from "@dogsbay/serialize-core";
 export const plugin = {
     name: "mkdocs",
     canImport: true,
@@ -12,7 +14,15 @@ export const plugin = {
         { flags: "--custom-css <files>", description: "Custom CSS files to copy (comma-separated)" },
         { flags: "--docusaurus-admonitions", description: "Enable Docusaurus-style ::: admonitions" },
     ],
-    exportOptions: [],
+    // NOT `--theme`: `dogsbay convert` already owns that flag for the Astro
+    // preset, with a default of "default" — which reached this exporter as
+    // `theme: name: default`, a theme MkDocs does not have, and every
+    // `convert --to mkdocs` project failed its first `mkdocs build`.
+    exportOptions: [
+        { flags: "--mkdocs-theme <name>", description: "MkDocs theme for the emitted mkdocs.yml (material | mkdocs | readthedocs)", default: "material" },
+        { flags: "--site-url <url>", description: "site_url for the emitted mkdocs.yml" },
+        { flags: "--repo-url <url>", description: "repo_url for the emitted mkdocs.yml" },
+    ],
     async import(source, opts) {
         const { pages, nav, config } = await importMkdocsProject(source, opts);
         // Attach config metadata for the exporter to consume
@@ -26,7 +36,104 @@ export const plugin = {
         if (extraCss && Array.isArray(extraCss)) {
             opts.extraCss = extraCss;
         }
-        return { pages, nav };
+        // Slugs are relative to `docs_dir`, not to the project root — so an
+        // `{% include %}` in a page means a file under THERE.
+        return { pages, nav, contentRoot: join(source, config.docsDir) };
+    },
+    /**
+     * Export: TreeNode pages + nav → a complete MkDocs project.
+     *
+     * `exportMkdocsProject` is I/O-free and returns a path → content map, so
+     * everything this method does is create directories and write bytes. It was
+     * written and unit-tested long before it was reachable: `cli.ts` declared
+     * `canExport: true` with no `export` method, and `resolveExporter()` filters
+     * on `canExport && f.export`, so `--to mkdocs` reported an unknown target
+     * while the serializer sat in the same package. That predicate exists
+     * BECAUSE of this plugin.
+     */
+    async export(pages, nav, output, opts) {
+        const result = exportMkdocsProject(pages, nav, {
+            siteName: opts.siteName ?? "Documentation",
+            siteUrl: opts.siteUrl,
+            repoUrl: opts.repoUrl,
+            theme: mkdocsTheme(opts),
+        });
+        for (const [filePath, content] of result.files) {
+            const fullPath = join(output, filePath);
+            mkdirSync(dirname(fullPath), { recursive: true });
+            writeFileSync(fullPath, content);
+        }
+        console.log(`Generated ${result.files.size} MkDocs files`);
+        // Mounted asset dirs, copied under docs/ at the ROOT their refs were
+        // rewritten to (`_assets` for an imported corpus, `images`/`assets` for
+        // hand-authored content). The serializer emits those refs relative to
+        // each page, so the file has to land exactly there or every image 404s
+        // with a clean exit code.
+        const mounts = opts.assetMounts;
+        for (const mount of mounts ?? []) {
+            if (!existsSync(mount.dir))
+                continue;
+            const root = mount.root ?? "_assets";
+            const dest = mount.into ? join(output, "docs", root, mount.into) : join(output, "docs", root);
+            mkdirSync(dest, { recursive: true });
+            if (mount.mediaOnly) {
+                copyMediaTree(mount.dir, dest);
+                continue;
+            }
+            // Skip symlinks rather than copy them: relative links are rewritten to
+            // ABSOLUTE paths into the source checkout, so the output only works on
+            // the machine that produced it. AsciiBinder corpora are full of them.
+            cpSync(mount.dir, dest, {
+                recursive: true,
+                dereference: false,
+                filter: (src) => !lstatSync(src).isSymbolicLink(),
+            });
+        }
+        // Co-located media next to the markdown (the mkdocs shape itself).
+        const sourceDir = opts.sourceDir;
+        if (sourceDir && existsSync(sourceDir))
+            copyMediaTree(sourceDir, join(output, "docs"));
+        if (!result.ledger.isEmpty) {
+            console.log(formatLedgerReport(result.ledger, "mkdocs"));
+        }
     },
 };
+const MEDIA_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".avif", ".mp4", ".webm", ".pdf", ".ico"]);
+/**
+ * Copy media files only, preserving the directory shape. Never follows a
+ * symlink: AsciiBinder corpora symlink every section back to one images
+ * tree, and following them copied a 64 MB tree once per link.
+ */
+function copyMediaTree(from, to) {
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const src = join(from, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            copyMediaTree(src, join(to, entry.name));
+            continue;
+        }
+        if (!MEDIA_EXT.has(extname(entry.name).toLowerCase()))
+            continue;
+        // Always copy. A same-size skip saved nothing measurable and silently
+        // kept a stale file when a one-character SVG edit left the size unchanged.
+        mkdirSync(to, { recursive: true });
+        copyFileSync(src, join(to, entry.name));
+    }
+}
+const MKDOCS_THEMES = new Set(["material", "mkdocs", "readthedocs"]);
+/**
+ * The MkDocs theme to write. `--mkdocs-theme` wins; a bare `theme` is honoured
+ * only when it names a theme MkDocs actually has, so the Astro preset default
+ * ("default") that `convert` passes through can never reach mkdocs.yml.
+ */
+function mkdocsTheme(opts) {
+    for (const candidate of [opts.mkdocsTheme, opts.theme]) {
+        if (typeof candidate === "string" && MKDOCS_THEMES.has(candidate))
+            return candidate;
+    }
+    return "material";
+}
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,CAAC,MAAM,MAAM,GAAiB;IAClC,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACpE,aAAa,EAAE;QACb,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,kCAAkC,EAAE,OAAO,EAAE,SAAS,EAAE;QAChG,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,gDAAgD,EAAE;QAC3F,EAAE,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,4CAA4C,EAAE;QAC5F,EAAE,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,yCAAyC,EAAE;KAC9F;IACD,aAAa,EAAE,EAAE;IAEjB,KAAK,CAAC,MAAM,CACV,MAAc,EACd,IAA6B;QAE7B,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvE,qDAAqD;QACrD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC;QACjD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC;QACpD,4DAA4D;QAC5D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,SAAiC,CAAC;QAC9D,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC3B,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACxB,CAAC;CACF,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/export/to-mkdocs-project.d.ts

@@ -1,4 +1,5 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
+import { ExportLedger } from "@dogsbay/serialize-core";
 /**
  * Options for project export.
  */
@@ -18,6 +19,8 @@ export interface MkdocsProjectOptions {
 export interface MkdocsProjectExport {
     files: Map<string, string>;
     mkdocsYml: string;
+    /** What could not be represented, per page. Empty is the goal, not the assumption. */
+    ledger: ExportLedger;
 }
 /**
  * Export a set of pages + navigation to a complete MkDocs project.

package/dist/export/to-mkdocs-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-mkdocs-project.d.ts","sourceRoot":"","sources":["../../src/export/to-mkdocs-project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGpE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EAAE,EACnB,GAAG,EAAE,OAAO,EAAE,EACd,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,CAuBrB"}
+{"version":3,"file":"to-mkdocs-project.d.ts","sourceRoot":"","sources":["../../src/export/to-mkdocs-project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,UAAU,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAgC,MAAM,yBAAyB,CAAC;AAGrF;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EAAE,EACnB,GAAG,EAAE,OAAO,EAAE,EACd,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,CAqErB"}

package/dist/export/to-mkdocs-project.js

@@ -1,26 +1,116 @@
-import { treeToMkdocs } from "./to-mkdocs.js";
+import { ExportLedger, frontmatterBlock, yamlScalar } from "@dogsbay/serialize-core";
+import { treeToMkdocs, hrefToSlugKey } from "./to-mkdocs.js";
 /**
  * Export a set of pages + navigation to a complete MkDocs project.
  * Returns file map (path → content) including mkdocs.yml and all .md files.
  */
 export function exportMkdocsProject(pages, nav, options) {
     const files = new Map();
+    const ledger = new ExportLedger();
+    const slugs = new Set(pages.map((p) => p.slug));
     // Generate markdown files
     const allTrees = [];
     for (const page of pages) {
-        const md = treeToMkdocs(page.tree);
-        const filePath = `docs/${page.slug}.md`;
-        files.set(filePath, md);
+        ledger.setPage(page.slug);
+        // A slug is a path under docs/. One that climbs out of it (`../x`),
+        // starts at the root, or carries a backslash is not a page name, it is a
+        // write outside the output tree. Refuse it, on the record.
+        if (!isSafeSlug(page.slug)) {
+            ledger.record({ feature: "page", action: "dropped", detail: `unsafe slug ${JSON.stringify(page.slug)} — not written` });
+            continue;
+        }
+        const path = `docs/${page.slug}.md`;
+        // Two pages on one slug (the importer strips `/index`, so `a.md` and
+        // `a/index.md` both arrive as `a`) used to overwrite silently — last one
+        // won, the ledger stayed empty, and the page count said 4 while 3 files
+        // existed. Keep the first, record the second.
+        if (files.has(path)) {
+            ledger.record({ feature: "page", action: "dropped", detail: `duplicate slug ${page.slug} — a second page with this slug was not written` });
+            continue;
+        }
+        const body = treeToMkdocs(page.tree, { pageSlug: page.slug, slugs, ledger });
+        // MkDocs reads `title:` from page meta; without it the nav label falls back
+        // to the first heading (fine) or the filename (not fine).
+        const fm = pageFrontmatter(page, ledger);
+        files.set(path, fm ? `${fm}\n\n${body}\n` : `${body}\n`);
         allTrees.push(page.tree);
     }
+    ledger.setPage(undefined);
     // Auto-detect required extensions from tree content
     const extensions = detectExtensions(allTrees, options.extraExtensions);
+    // Resolve nav against what was WRITTEN, not what was submitted: a page
+    // refused above (unsafe slug, duplicate) is still in `slugs`, and a nav
+    // entry or the home redirect pointing at it would be a link to a 404.
+    const written = new Set([...files.keys()].filter((k) => k.startsWith("docs/") && k.endsWith(".md")).map((k) => k.slice(5, -3)));
     // Convert nav to mkdocs.yml nav format
-    const navYaml = navToYaml(nav, pages);
+    const navYaml = navToYaml(nav, written, ledger);
+    // Nothing at `/`. MkDocs serves `docs/index.md` as the site root and
+    // emits NOTHING there otherwise — no 404, no redirect, just no
+    // `site/index.html` — so a corpus whose nav starts at `welcome.md` (the
+    // OpenShift shape) published a site whose front door was a 404. The
+    // Docusaurus exporter closes the same hole with `src/pages/index.js`; this
+    // is the MkDocs equivalent: a meta-refresh to the first nav page. Kept out
+    // of `nav:` (MkDocs builds unlisted pages without listing them) and out of
+    // search.
+    if (!files.has("docs/index.md")) {
+        const first = firstNavSlug(nav, written);
+        if (first) {
+            files.set("docs/index.md", homeRedirect(options.siteName, first));
+        }
+        else {
+            ledger.record({ feature: "home-page", action: "dropped", detail: "no index page and no nav entry to redirect to — the site root will 404" });
+        }
+    }
     // Generate mkdocs.yml
     const yml = buildMkdocsYml(options, extensions, navYaml);
     files.set("mkdocs.yml", yml);
-    return { files, mkdocsYml: yml };
+    return { files, mkdocsYml: yml, ledger };
+}
+function isSafeSlug(slug) {
+    if (!slug || slug.startsWith("/") || slug.includes("\\"))
+        return false;
+    return !slug.split("/").some((seg) => seg === ".." || seg === "." || seg === "");
+}
+/**
+ * Frontmatter keys MkDocs Material reads from page meta. Anything else the
+ * source carried is recorded as dropped rather than silently discarded — a
+ * mkdocs → mkdocs round trip that loses `tags:` looks like success otherwise.
+ */
+const MATERIAL_META = new Set(["tags", "hide", "status", "template", "icon", "search", "subtitle"]);
+function pageFrontmatter(page, ledger) {
+    const fm = (page.frontmatter ?? {});
+    const entries = [];
+    const rawTitle = fm.title ?? page.title;
+    const title = typeof rawTitle === "string" ? rawTitle : page.title;
+    if (title)
+        entries.push(["title", title]);
+    if (typeof fm.description === "string")
+        entries.push(["description", fm.description]);
+    const extra = [];
+    for (const [key, value] of Object.entries(fm)) {
+        if (key === "title" || key === "description")
+            continue;
+        if (MATERIAL_META.has(key)) {
+            if (Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number")) {
+                extra.push(`${key}:\n${value.map((v) => `  - ${yamlScalar(String(v))}`).join("\n")}`);
+            }
+            else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                extra.push(`${key}: ${typeof value === "string" ? yamlScalar(value) : String(value)}`);
+            }
+            else {
+                ledger.record({ feature: `frontmatter:${key}`, action: "dropped", detail: "unsupported value shape" });
+            }
+            continue;
+        }
+        ledger.record({ feature: `frontmatter:${key}`, action: "dropped", detail: "no MkDocs equivalent" });
+    }
+    if (entries.length === 0 && extra.length === 0)
+        return "";
+    const base = entries.length ? frontmatterBlock(entries) : "";
+    if (!extra.length)
+        return base;
+    const inner = base ? base.replace(/\n---$/, "") : "---";
+    return `${inner}\n${extra.join("\n")}\n---`;
 }
 // ── Extension Detection ─────────────────────────────────────────
 /**
@@ -29,8 +119,12 @@ export function exportMkdocsProject(pages, nav, options) {
  */
 function detectExtensions(allTrees, extra) {
     const found = new Set();
-    // Always include these basics
+    // Always-on. `attr_list` because every heading carries `{ #id }`; the rest
+    // are cheap and what the serializer emits assumes them.
     found.add("toc:\n    permalink: true");
+    found.add("attr_list");
+    found.add("md_in_html");
+    found.add("tables");
     for (const tree of allTrees) {
         walkForExtensions(tree, found);
     }
@@ -53,40 +147,92 @@ function walkForExtensions(nodes, found) {
             case "tabs":
             case "tab":
                 found.add("pymdownx.tabbed:\n    alternate_style: true");
+                found.add("pymdownx.superfences");
                 break;
-            case "code": {
+            case "code":
                 found.add("pymdownx.highlight:\n    anchor_linenums: true");
                 found.add("pymdownx.superfences");
-                if (node.props?.hasAnnotations) {
-                    found.add("pymdownx.superfences");
-                }
                 break;
-            }
+            case "diagram":
+                found.add("pymdownx.superfences:\n    custom_fences:\n      - name: mermaid\n        class: mermaid\n        format: !!python/name:pymdownx.superfences.fence_code_format");
+                break;
             case "deflist":
             case "dt":
             case "dd":
                 found.add("def_list");
                 break;
-            case "html-container":
-                found.add("md_in_html");
-                break;
             case "task-list":
             case "task-item":
                 found.add("pymdownx.tasklist:\n    custom_checkbox: true");
                 break;
+            // Checkboxes are `list-item` nodes with `props.checked` — the shape the
+            // parser emits and the serializer reads; there is no `task-item` node.
+            case "list-item":
+                if (node.props?.checked !== undefined)
+                    found.add("pymdownx.tasklist:\n    custom_checkbox: true");
+                break;
             case "math":
+            case "math-block":
             case "math-inline":
                 found.add("pymdownx.arithmatex:\n    generic: true");
                 break;
             case "footnote":
-            case "footnote-ref":
+            case "footnote-list":
+            case "footnote-def":
                 found.add("footnotes");
                 break;
+            // The serializer emits `:octicons-arrow-right-24:` on a card link.
+            case "card":
+            case "cards":
+            case "link-card":
+                found.add(EMOJI_EXT);
+                break;
+            // An unrealized include is emitted as `--8<-- "path"`.
+            case "include":
+                found.add("pymdownx.snippets");
+                break;
         }
+        if (node.inline)
+            walkInlineForExtensions(node.inline, found);
         if (node.children)
             walkForExtensions(node.children, found);
     }
 }
+const EMOJI_EXT = "pymdownx.emoji:\n    emoji_index: !!python/name:material.extensions.emoji.twemoji\n    emoji_generator: !!python/name:material.extensions.emoji.to_svg";
+/**
+ * Inline nodes NEST — a highlight inside a link, a struck span inside bold.
+ * Walking one level detected `==x==` at top level and missed the same mark
+ * one link deeper, so the extension was absent and the marks rendered as
+ * literal `==`.
+ */
+function walkInlineForExtensions(nodes, found) {
+    for (const inline of nodes) {
+        switch (inline.type) {
+            case "footnote-ref":
+                found.add("footnotes");
+                break;
+            case "highlight":
+                found.add("pymdownx.mark");
+                break;
+            case "kbd":
+                found.add("pymdownx.keys");
+                break;
+            case "math":
+                found.add("pymdownx.arithmatex:\n    generic: true");
+                break;
+            case "icon":
+                found.add(EMOJI_EXT);
+                break;
+            case "text":
+                if (inline.strikethrough)
+                    found.add("pymdownx.tilde");
+                break;
+        }
+        const kids = inline.children;
+        if (kids)
+            walkInlineForExtensions(kids, found);
+    }
+}
 // ── Nav Conversion ──────────────────────────────────────────────
 /**
  * Convert NavItem[] to mkdocs.yml nav YAML string.
@@ -95,82 +241,140 @@ function walkForExtensions(nodes, found) {
  *   - Home: index.md
  *   - Section:
  *       - Page: path.md
+ *
+ * An href is matched EXACTLY against the exported slugs (after stripping the
+ * origin, query, fragment and slashes). The previous last-segment fuzzy match
+ * would map `/installing/index/` to whichever page's slug ended in `index`
+ * first — wrong for any corpus with more than one index page.
  */
-function navToYaml(items, pages, indent = 2) {
+function navToYaml(items, slugs, ledger, indent = 2) {
     const lines = [];
     const prefix = " ".repeat(indent);
     for (const item of items) {
-        if (item.children && item.children.length > 0) {
-            // Group with children
-            if (item.href) {
-                // Group has its own page + children
-                lines.push(`${prefix}- ${item.label}:`);
-                const slug = hrefToSlug(item.href, pages);
-                if (slug) {
-                    lines.push(`${prefix}    - ${item.label}: ${slug}.md`);
-                }
-                lines.push(navToYaml(item.children, pages, indent + 4));
-            }
-            else {
-                // Group without own page
-                lines.push(`${prefix}- ${item.label}:`);
-                lines.push(navToYaml(item.children, pages, indent + 4));
-            }
+        const label = yamlScalar(item.label ?? "");
+        const target = item.href ? navTarget(item.href, slugs) : null;
+        // Children FIRST, so a group whose entries all failed to resolve is
+        // skipped rather than emitted as `- Group:` — a null section, which is a
+        // hard `mkdocs build` configuration abort, not a warning.
+        const inner = item.children?.length ? navToYaml(item.children, slugs, ledger, indent + 4) : "";
+        if (item.href && !target) {
+            ledger.record({ feature: "nav-entry", action: "dropped", detail: `${item.label ?? ""} → ${item.href}: not an exported page` });
         }
-        else if (item.href) {
-            // Leaf page
-            const slug = hrefToSlug(item.href, pages);
-            if (slug) {
-                lines.push(`${prefix}- ${item.label}: ${slug}.md`);
-            }
+        if (inner) {
+            lines.push(`${prefix}- ${label}:`);
+            if (target)
+                lines.push(`${prefix}    - ${label}: ${target}`);
+            lines.push(inner);
+        }
+        else if (target) {
+            lines.push(`${prefix}- ${label}: ${target}`);
+        }
+        else if (item.children?.length) {
+            ledger.record({ feature: "nav-entry", action: "dropped", detail: `${item.label ?? ""}: section with no exported pages` });
         }
     }
     return lines.filter(Boolean).join("\n");
 }
 /**
- * Convert an href ("/mkdocs/configuring") to a slug ("configuring")
- * by matching against known pages.
+ * What a nav href becomes in mkdocs.yml: a `slug.md` for an exported page,
+ * the URL itself for an external link (MkDocs supports `- Label: https://…`
+ * natively), or null when it names nothing we emit.
  */
-function hrefToSlug(href, pages) {
-    // Strip leading path prefix — take the last segment(s)
-    const parts = href.replace(/^\//, "").split("/");
-    // Try matching against page slugs
-    for (const page of pages) {
-        // Exact match on slug
-        if (parts.join("/") === page.slug || parts.slice(1).join("/") === page.slug) {
-            return page.slug;
+function navTarget(href, slugs) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//"))
+        return href;
+    const slug = hrefToSlug(href, slugs);
+    return slug ? `${slug}.md` : null;
+}
+function hrefToSlug(href, slugs) {
+    const key = hrefToSlugKey(href);
+    if (slugs.has(key))
+        return key;
+    if (slugs.has(`${key}/index`))
+        return `${key}/index`;
+    if (key === "" && slugs.has("index"))
+        return "index";
+    return null;
+}
+/** First nav entry that resolves to an exported page, depth-first. */
+function firstNavSlug(nav, slugs) {
+    for (const item of nav) {
+        if (item.href && !/^[a-z][a-z0-9+.-]*:/i.test(item.href) && !item.href.startsWith("//")) {
+            const slug = hrefToSlug(item.href, slugs);
+            if (slug)
+                return slug;
         }
-        // Match on last segment
-        if (parts[parts.length - 1] === page.slug.split("/").pop()) {
-            return page.slug;
+        if (item.children?.length) {
+            const inner = firstNavSlug(item.children, slugs);
+            if (inner)
+                return inner;
         }
     }
-    // Fallback: use last path segment
-    return parts[parts.length - 1] || null;
+    return null;
+}
+/**
+ * A root page that forwards to `slug`. The URL is RELATIVE (`welcome/`, or
+ * `a/b/` — a trailing `index` stripped, since `use_directory_urls: true`,
+ * which the emitted config sets, serves `a/index.md` at `a/`), so it is
+ * right under any `site_url` path prefix. The markdown link is the
+ * no-refresh fallback and lets `mkdocs build` validate the target — it is
+ * also the one MkDocs rewrites if someone later flips `use_directory_urls`;
+ * the meta URL is not. Not in `nav:`, so MkDocs still lists it in
+ * sitemap.xml (no per-page exclusion exists) and titles it `Site - Site`.
+ */
+function homeRedirect(siteName, slug) {
+    const url = slug.replace(/(^|\/)index$/, "$1").replace(/\/?$/, "/");
+    // A slug is a path, not an attribute value: encode per segment for the
+    // meta URL, and use the `<…>` destination form so a space survives the
+    // markdown link.
+    const href = url.split("/").map(encodeURIComponent).join("/");
+    return [
+        "---",
+        `title: ${yamlScalar(siteName)}`,
+        "search:",
+        "  exclude: true",
+        "---",
+        "",
+        `<meta http-equiv="refresh" content="0; url=${href}">`,
+        "",
+        `Redirecting to [${url}](<${slug}.md>)…`,
+        "",
+    ].join("\n");
 }
 // ── YAML Generation ─────────────────────────────────────────────
 function buildMkdocsYml(options, extensions, navYaml) {
     const lines = [];
-    lines.push(`site_name: ${options.siteName}`);
+    lines.push(`site_name: ${yamlScalar(options.siteName)}`);
     if (options.siteUrl)
-        lines.push(`site_url: ${options.siteUrl}`);
+        lines.push(`site_url: ${yamlScalar(options.siteUrl)}`);
     if (options.repoUrl)
-        lines.push(`repo_url: ${options.repoUrl}`);
+        lines.push(`repo_url: ${yamlScalar(options.repoUrl)}`);
+    lines.push("use_directory_urls: true");
     lines.push("");
     // Theme
     lines.push("theme:");
     lines.push(`  name: ${options.theme ?? "material"}`);
     lines.push("  features:");
     lines.push("    - content.code.copy");
-    lines.push("    - navigation.instant");
+    lines.push("    - content.tabs.link");
     lines.push("    - navigation.tracking");
+    // Material renders the WHOLE nav into every page unless told to prune.
+    // Measured on OpenShift 4.22 (1,800 pages, 2,100 nav entries): 1 MB per
+    // page, 1.9 GB total — over GitHub Pages' 1 GB site limit — with the nav
+    // as 95% of every file. `navigation.prune` keeps only the active path;
+    // Material's own docs recommend it for sites with hundreds of pages.
+    lines.push("    - navigation.prune");
     lines.push("    - navigation.sections");
-    lines.push("    - toc.integrate");
+    lines.push("    - navigation.indexes");
+    lines.push("    - navigation.top");
+    lines.push("    - toc.follow");
     lines.push("");
     // Nav
-    lines.push("nav:");
-    lines.push(navYaml);
-    lines.push("");
+    if (navYaml) {
+        lines.push("nav:");
+        lines.push(navYaml);
+        lines.push("");
+    }
     // Extensions
     lines.push("markdown_extensions:");
     for (const ext of extensions) {
@@ -179,7 +383,7 @@ function buildMkdocsYml(options, extensions, navYaml) {
             const extLines = ext.split("\n");
             lines.push(`  - ${extLines[0]}`);
             for (let i = 1; i < extLines.length; i++) {
-                lines.push(`      ${extLines[i].trimStart()}`);
+                lines.push(`  ${extLines[i]}`);
             }
         }
         else {