@dogsbay/format-mkdocs 0.2.0-beta.14 → 0.2.0-beta.141

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,152 @@ 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)}`);
+    // `copyright:` is the only footer string MkDocs offers, so the attribution
+    // is appended to it rather than replacing it. Material renders it as HTML.
+    const footer = [
+        options.copyright,
+        options.poweredBy !== false
+            // Single-quoted attribute: a double quote here would be escaped by the
+            // YAML scalar and the emitted mkdocs.yml becomes unreadable.
+            ? "Powered by <a href='https://dogsbay.ai'>DogsBay</a>"
+            : undefined,
+    ].filter(Boolean);
+    if (footer.length > 0)
+        lines.push(`copyright: ${yamlScalar(footer.join(" &middot; "))}`);
+    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 +395,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 {
@@ -189,4 +405,3 @@ function buildMkdocsYml(options, extensions, navYaml) {
     lines.push("");
     return lines.join("\n");
 }
-//# sourceMappingURL=to-mkdocs-project.js.map

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

@@ -1,6 +1,55 @@
-import type { TreeNode } from "../tree.js";
 /**
- * Convert a TreeNode[] back to MkDocs-compatible Markdown.
+ * MkDocs serializer — TreeNode[] → MkDocs (Python-Markdown + PyMdown) Markdown.
+ *
+ * Built on `@dogsbay/serialize-core`: shape-tolerant leaf reads, the shared
+ * inline walk, and a ledger for what could not be represented. The first
+ * version of this file predated the core and read `node.children` only, so
+ * every heading and paragraph parsed from real dogsbay-md — where the text is
+ * on `node.inline` — serialized as `# ` with no title. The tier-3 export
+ * conformance suite caught it the moment the exporter was wired in.
+ *
+ * Python-Markdown differs from CommonMark in ways that matter here:
+ *
+ * - Nested block content inside a list item, admonition or tab must be
+ *   indented by FOUR spaces. Two-space continuation (fine in CommonMark)
+ *   detaches the block and renders it at top level.
+ * - There is no native tabs/steps/cards syntax; PyMdown supplies
+ *   `=== "Tab"`, and the rest is expressed with `attr_list` / `md_in_html`.
+ * - Heading ids come from `attr_list` (`# Title { #id }`), and the corpus
+ *   cross-references depend on the AUTHORED ids surviving — AsciiDoc-derived
+ *   ids like `additional-resources_welcome-index` would not be regenerated by
+ *   the toc extension's slugifier.
  */
-export declare function treeToMkdocs(nodes: TreeNode[]): string;
-//# sourceMappingURL=to-mkdocs.d.ts.map
+import type { TreeNode, NavItem } from "@dogsbay/types";
+import { ExportLedger } from "@dogsbay/serialize-core";
+export interface MkdocsSerializeOptions {
+    /**
+     * Slug of the page being serialized (`welcome/oke_about`). Used to make
+     * site-rooted links (`/welcome/index/#anchor`) and asset refs
+     * (`/images/x.png`) RELATIVE to the emitted file, which is how MkDocs
+     * resolves and validates them. Without it links are emitted verbatim.
+     */
+    pageSlug?: string;
+    /**
+     * Every page slug in the export. A site-rooted href is rewritten to a
+     * relative `.md` link only when it names a page we are actually emitting;
+     * anything else (an asset, an external route) is left alone.
+     */
+    slugs?: ReadonlySet<string>;
+    /** Loss recorder. One per export run; entries are stamped with the page. */
+    ledger?: ExportLedger;
+}
+/**
+ * Convert a TreeNode[] to MkDocs-compatible Markdown.
+ */
+export declare function treeToMkdocs(nodes: TreeNode[], options?: MkdocsSerializeOptions): string;
+/**
+ * Site-rooted page links → relative `.md` links, which MkDocs resolves,
+ * validates, and rewrites for `use_directory_urls`. Only rewritten when the
+ * target is a page in this export; everything else passes through so an
+ * asset or external route is never turned into a dead `.md`.
+ */
+export declare function mkdocsHref(href: string): string;
+/** Normalise an href or slug to the slug form pages are keyed by. */
+export declare function hrefToSlugKey(href: string): string;
+export type { NavItem };