@dogsbay/format-mkdocs 0.2.0-beta.13 → 0.2.0-beta.131

package/dist/export/to-mkdocs.js

@@ -1,178 +1,979 @@
+import { walkInline, applyTextFlags, renderLeaf, indent, prefixLines, pickCodeFence, codeSpan, stripHtml, inlineHtmlToMarkdown, renderUnknownNode, listStart, calloutVariant, leafHtml, isSafeHref, markdownDestination, markdownLatex, safeAnchorId, footnoteLabel, renderAroundGroup, } from "@dogsbay/serialize-core";
+// Module-level, saved and restored around each treeToMkdocs call. Correct
+// for synchronous nesting only: nothing in this module may `await`, or one
+// page's context bleeds into the next.
+let ctx = {
+    pageSlug: "",
+};
 /**
- * Convert a TreeNode[] back to MkDocs-compatible Markdown.
+ * Convert a TreeNode[] to MkDocs-compatible Markdown.
  */
-export function treeToMkdocs(nodes) {
-    return nodes.map(nodeToMkdocs).join("\n\n");
+export function treeToMkdocs(nodes, options = {}) {
+    const prev = ctx;
+    ctx = { pageSlug: "", ...options };
+    try {
+        return joinBlocks(nodes);
+    }
+    finally {
+        ctx = prev;
+    }
+}
+function report(feature, detail, action = "degraded") {
+    ctx.ledger?.record({ feature, detail, action });
 }
+// ── Block dispatcher ────────────────────────────────────
 function nodeToMkdocs(node) {
     switch (node.type) {
         case "frontmatter":
             return `---\n${node.props?.content ?? ""}\n---`;
         case "references":
             return referencesToMkdocs(node);
+        case "heading":
+            return headingToMkdocs(node);
+        case "paragraph":
+            return escapeBlockStart(leafContent(node));
+        case "prose":
+            return proseToMkdocs(node);
         case "callout":
             return calloutToMkdocs(node);
         case "details":
             return detailsToMkdocs(node);
+        case "accordion":
+            // pymdownx.details folds, one per item, titled with the item's label.
+            // Material has no accordion grouping, so each folds on its own
+            return (node.children ?? [])
+                .map((c) => c.type === "accordion-item"
+                ? detailsToMkdocs({ ...c, props: { title: (c.props?.label ?? c.props?.title), open: c.props?.open } })
+                : nodeToMkdocs(c))
+                .filter(Boolean)
+                .join("\n\n");
+        case "accordion-item":
+            // A lone item (outside an accordion) is one fold, as inside one
+            return detailsToMkdocs({ ...node, props: { title: (node.props?.label ?? node.props?.title), open: node.props?.open } });
         case "tabs":
-            return tabsToMkdocs(node);
+            return renderAroundGroup(node, "tab", tabsToMkdocs, nodeToMkdocs, "\n\n");
         case "tab":
             return tabToMkdocs(node);
         case "code":
             return codeToMkdocs(node);
         case "diagram":
             return diagramToMkdocs(node);
-        case "annotation-list":
-            return annotationListToMkdocs(node);
-        case "heading":
-            return headingToMkdocs(node);
-        case "paragraph":
-            return childrenToMkdocs(node);
-        case "prose":
-            return node.html ?? "";
+        case "math-block":
+        case "math":
+            return mathBlockToMkdocs(node);
+        case "table":
+            return tableToMkdocs(node);
         case "blockquote":
-            return blockquoteToMkdocs(node);
+            return prefixLines(childrenToMkdocs(node), "> ");
         case "ordered-list":
             return orderedListToMkdocs(node);
         case "unordered-list":
             return unorderedListToMkdocs(node);
         case "list-item":
+            return listItemToMkdocs(node);
+        case "deflist":
+            return deflistToMkdocs(node);
+        case "dt":
+            return escapeBlockStart(leafContent(node));
+        case "dd":
+            return escapeBlockStart(leafContent(node));
+        case "steps":
+        case "substeps":
+            return stepsToMkdocs(node);
+        case "step":
+            // A step reached outside stepsToMkdocs: its title is its inline text.
+            return [escapeBlockStart(leafContent(node)), childrenToMkdocs(node)].filter(Boolean).join("\n\n");
+        case "annotation-list":
             return childrenToMkdocs(node);
-        case "html-container":
-            return htmlContainerToMkdocs(node);
+        case "link-button": {
+            const raw = node.props?.href ?? "";
+            const href = raw && isSafeHref(raw) ? mkdocsHref(raw) : "";
+            if (raw && !href)
+                report("link-button", `unsafe link target dropped (${raw.slice(0, 40)})`);
+            const text = leafContent(node) || escapeProse(href);
+            return href ? `[${text}](${markdownDestination(href)}){ .md-button .md-button--primary }` : text;
+        }
         case "hr":
             return "---";
         case "html":
-            return node.html ?? "";
+            return relativizeHtmlAssets(node.html ?? "");
+        case "html-container":
+            // Parsed from raw HTML (a one-line `<details>` body), the content is in
+            // `html` with no children; rendering only children dropped it
+            if (!node.children?.length && node.html)
+                return relativizeHtmlAssets(node.html);
+            return htmlContainerToMkdocs(node);
+        case "figure": {
+            const caption = node.props?.caption;
+            const inner = childrenToMkdocs(node);
+            if (!caption)
+                return inner;
+            return `<figure markdown>\n\n${inner}\n\n<figcaption>${htmlText(caption)}</figcaption>\n</figure>`;
+        }
+        case "card":
+            return cardToMkdocs(node);
+        case "cards":
+        case "grid":
+            return cardsToMkdocs(node);
+        case "link-card":
+            return cardToMkdocs(node);
+        case "youtube":
+            return youtubeToMkdocs(node);
+        case "api-class":
+        case "api-member":
+            return apiSymbolToMkdocs(node);
+        case "api-doc":
+            return apiDocToMkdocs(node);
+        case "api-params":
+            return apiParamsToMkdocs(node);
+        case "api-source":
+            return apiSourceToMkdocs(node);
+        case "footnote-list":
+            return (node.children ?? []).map(nodeToMkdocs).filter(Boolean).join("\n");
+        case "footnote-def":
+            return footnoteDefToMkdocs(node);
+        case "related": {
+            // "Additional resources" — the title lives in props; children are the
+            // link list. Dropping the label floats the links with no context.
+            const title = (node.props?.title ?? "").trim();
+            const body = childrenToMkdocs(node);
+            if (!title)
+                return body;
+            return `**${escapeProse(title)}**\n\n${body}`;
+        }
+        case "include": {
+            // Includes are realized upstream (convert / site build). One that
+            // reaches the serializer is unresolved: emit the snippet form so the
+            // reference is visible in the output rather than vanishing, and say so.
+            const src = node.props?.src ?? node.props?.path ?? "";
+            report("include", `unrealized include ${src} emitted as a --8<-- snippet`);
+            return `--8<-- "${src}"`;
+        }
         default:
-            return node.html ?? childrenToMkdocs(node);
+            // `renderChildren` is what keeps an unknown CONTAINER's content: without
+            // it the html policy returns a comment for a node that has children and
+            // no html, and the ledger says "no content to preserve" — false.
+            return renderUnknownNode(node, {
+                policy: "html",
+                renderChildren: (kids) => joinBlocks(kids),
+                // The bare type: the feature name in MKDOCS_CAPABILITIES (a
+                // `node:` prefix made every recorded loss look undeclared)
+                report: (type, detail) => report(type, detail ?? ""),
+                join: "\n\n",
+            });
     }
 }
+// ── Inline rendering ────────────────────────────────────
+/**
+ * MkDocs inline syntax as emitters over the core's shared walk.
+ *
+ * Exhaustive on purpose: an omitted key routes through the core's
+ * plain-text degradation, which is the right default for a NEW variant and
+ * the wrong behaviour for one PyMdown genuinely supports.
+ */
+const MKDOCS_INLINE = {
+    text: (node) => applyTextFlags(escapeProse(node.text), node, {
+        bold: (s) => `**${s}**`,
+        italic: (s) => `*${s}*`,
+        strike: (s) => `~~${s}~~`,
+    }),
+    link: (node, c) => {
+        // Python-Markdown does not filter URL schemes.
+        if (!isSafeHref(node.href)) {
+            c.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+            return c.recurse(node.children);
+        }
+        return `[${c.recurse(node.children)}](${markdownDestination(mkdocsHref(node.href))}${linkTitle(node.title)})${attrSuffix(node.attrs)}`;
+    },
+    image: (node, c) => {
+        if (!isSafeHref(node.src, "image")) {
+            c.report("image", `unsafe image source dropped (${node.src.slice(0, 40)})`);
+            return escapeProse(node.alt ?? "");
+        }
+        const alt = (node.alt ?? "").replace(/\]/g, "\\]");
+        const title = linkTitle(node.title);
+        const attrs = { ...(node.attrs ?? {}) };
+        if (node.width)
+            attrs.width = String(node.width);
+        if (node.height)
+            attrs.height = String(node.height);
+        return `![${alt}](${markdownDestination(mkdocsAssetPath(node.src))}${title})${attrSuffix(attrs)}`;
+    },
+    code: (node) => codeSpan(node.text),
+    highlight: (node, c) => `==${c.recurse(node.children)}==`,
+    "footnote-ref": (node) => `[^${footnoteLabel(node.label)}]`,
+    // pymdownx.keys: `++ctrl+alt+del++`
+    // Key names only: anything else in a key was inline HTML to Python-Markdown.
+    // A key name as pymdownx.keys knows it; anything else as a quoted key
+    // (its text, escaped by the extension), never as inline HTML.
+    kbd: (node) => `++${node.keys
+        .map((k) => {
+        const name = k.toLowerCase().replace(/\s+/g, "-");
+        return /^[a-z0-9-]+$/.test(name) ? name : `"${k.replace(/["\\\r\n]/g, "")}"`;
+    })
+        .join("+")}++`,
+    math: (node) => `$${markdownLatex(node.latex)}$`,
+    icon: (node) => `:${node.name.replace(/[^A-Za-z0-9_-]/g, "-")}:`,
+    "html-inline": (node) => relativizeHtmlAssets(node.html ?? ""),
+    // A two-space hard break inside an indented block is fragile; `<br>` is not.
+    break: () => "<br>",
+};
+/**
+ * Escape prose for Python-Markdown.
+ *
+ * `<cluster-name>` in running text is an HTML tag to Python-Markdown and the
+ * placeholder disappears from the rendered page. `\<` is NOT an escape in
+ * this dialect (its ESCAPED_CHARS has no `<`), so the entity is the only
+ * form that survives. Emphasis and code markers are backslash-escaped so a
+ * literal `*` or `_` in prose cannot open a span.
+ */
+function escapeProse(text) {
+    // Emoji shortcodes (`:man_raising_hand:`) must keep their underscores.
+    const parts = text.split(/(:[a-z0-9_+-]+:)/i);
+    return parts
+        .map((part, i) => {
+        if (i % 2 === 1)
+            return part;
+        return part
+            .replace(/&(?![a-zA-Z#][a-zA-Z0-9]*;)/g, "&amp;")
+            .replace(/<(?=[A-Za-z/!?])/g, "&lt;")
+            .replace(/([*`[\]])/g, "\\$1")
+            // Intraword `_` is literal to Python-Markdown (snake_case is safe);
+            // only an underscore at a word edge can open or close emphasis.
+            .replace(/(^|[^A-Za-z0-9])_|_(?=[^A-Za-z0-9]|$)/g, (m) => m.replace("_", "\\_"))
+            .replace(/~~/g, "\\~\\~");
+    })
+        .join("");
+}
+/**
+ * A block of prose that BEGINS with something Python-Markdown reads as
+ * structure — `# `, `> `, `- `, `1. `, `!!! `, `=== `, a def_list `:   ` —
+ * becomes that structure. Neutralise the first character of the first line.
+ */
+function escapeBlockStart(block) {
+    if (!block)
+        return block;
+    const first = block.split("\n", 1)[0];
+    if (/^(#{1,6}\s|>|[-+]\s|\d+[.)]\s|---|\+\+\+)/.test(first))
+        return `\\${block}`;
+    if (/^!!!/.test(first))
+        return `\\${block}`;
+    if (/^\?\?\?/.test(first))
+        return `&#63;${block.slice(1)}`;
+    if (/^===/.test(first))
+        return `&#61;${block.slice(1)}`;
+    if (/^:\s{3}/.test(first))
+        return `&#58;${block.slice(1)}`;
+    return block;
+}
+/**
+ * Two adjacent lists — or two adjacent tab groups — are ONE list / one tab
+ * set to Python-Markdown (`1. a` then `- b` merge into a single `<ol>`, and
+ * `===!` is not a separator in pymdownx 10). An empty HTML comment between
+ * them is invisible and keeps them apart.
+ */
+const LIST_TYPES = new Set(["ordered-list", "unordered-list"]);
+function joinBlocks(nodes) {
+    const out = [];
+    let prev;
+    for (const node of nodes) {
+        const text = nodeToMkdocs(node);
+        if (!text)
+            continue;
+        if (prev && ((LIST_TYPES.has(prev.type) && LIST_TYPES.has(node.type)) || (prev.type === "tabs" && node.type === "tabs"))) {
+            out.push("<!-- -->");
+        }
+        out.push(text);
+        prev = node;
+    }
+    return out.join("\n\n");
+}
+/** A link title for Python-Markdown: one line, `"` as an entity. */
+function linkTitle(title) {
+    return title ? ` "${escapeProse(title.replace(/\s*[\r\n]+\s*/g, " ")).replace(/"/g, "&quot;")}"` : "";
+}
+/** Text for a raw HTML element (a figcaption, an attribute). */
+function htmlText(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function inlineToMkdocs(nodes) {
+    return walkInline(groupFormatRuns(nodes), {
+        emitters: MKDOCS_INLINE,
+        // Inline nodes without their own emitter fall back to plain text.
+        escape: escapeProse,
+        report: (feature, detail) => report(feature, detail ?? ""),
+    });
+}
+/**
+ * Wrap CONSECUTIVE nodes sharing the same bold/italic/strike flags in one
+ * mark pair instead of per-node wrapping. The parser splits a bold run at a
+ * code span (`**formatted `code` text**` arrives as three flagged nodes);
+ * per-node emission produced `**formatted**** ****text**` — an empty
+ * `** **` pair Python-Markdown renders as literal asterisks. Same fix as
+ * format-obsidian's groupFormatRuns.
+ */
+function groupFormatRuns(nodes) {
+    const flagsOf = (n) => {
+        const f = n;
+        return `${f.bold ? "b" : ""}${f.italic ? "i" : ""}${f.strikethrough ? "s" : ""}`;
+    };
+    const flaggable = (n) => n.type === "text" || n.type === "code";
+    const out = [];
+    let i = 0;
+    while (i < nodes.length) {
+        const key = flagsOf(nodes[i]);
+        if (!key || !flaggable(nodes[i])) {
+            out.push(nodes[i]);
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < nodes.length && flaggable(nodes[j]) && flagsOf(nodes[j]) === key)
+            j++;
+        if (j === i + 1 && nodes[i].type === "text") {
+            out.push(nodes[i]);
+            i = j;
+            continue;
+        }
+        const run = nodes.slice(i, j).map((n) => {
+            const clone = { ...n };
+            delete clone.bold;
+            delete clone.italic;
+            delete clone.strikethrough;
+            return clone;
+        });
+        let inner = walkInline(run, { emitters: MKDOCS_INLINE, escape: escapeProse });
+        const lead = inner.match(/^\s*/)[0];
+        const tail = inner.match(/\s*$/)[0];
+        inner = inner.slice(lead.length, inner.length - tail.length || undefined);
+        if (inner) {
+            let open = "";
+            let close = "";
+            if (key.includes("s")) {
+                open += "~~";
+                close = "~~" + close;
+            }
+            if (key.includes("i")) {
+                open += "*";
+                close = "*" + close;
+            }
+            if (key.includes("b")) {
+                open += "**";
+                close = "**" + close;
+            }
+            // Already-serialized markdown riding the html-inline pass-through.
+            out.push({ type: "html-inline", html: lead + open + inner + close + tail });
+        }
+        else if (lead) {
+            out.push({ type: "text", text: lead });
+        }
+        i = j;
+    }
+    return out;
+}
+/** `{ .class #id key="value" }` for attr_list, or "" when there is nothing. */
+function attrSuffix(attrs) {
+    if (!attrs)
+        return "";
+    const parts = [];
+    if (attrs.id)
+        parts.push(`#${attrs.id}`);
+    if (attrs.class)
+        parts.push(...attrs.class.split(/\s+/).filter(Boolean).map((cls) => `.${cls}`));
+    for (const [k, v] of Object.entries(attrs)) {
+        if (k === "id" || k === "class" || v === undefined)
+            continue;
+        parts.push(`${k}="${v.replace(/"/g, "&quot;")}"`);
+    }
+    return parts.length ? `{ ${parts.join(" ")} }` : "";
+}
+// ── Links and assets ────────────────────────────────────
+/** Directory of the current page's emitted file, as path segments. */
+function pageDirSegments() {
+    const parts = ctx.pageSlug.split("/").filter(Boolean);
+    parts.pop();
+    return parts;
+}
+/** `target` (site-rooted, no leading slash) relative to the current page's directory. */
+function relativeToPage(target) {
+    const from = pageDirSegments();
+    const to = target.split("/").filter(Boolean);
+    let i = 0;
+    while (i < from.length && i < to.length && from[i] === to[i])
+        i++;
+    const up = from.slice(i).map(() => "..");
+    const rel = [...up, ...to.slice(i)].join("/");
+    return rel || ".";
+}
+/**
+ * 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 function mkdocsHref(href) {
+    if (!href || /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#") || href.startsWith("//")) {
+        return href;
+    }
+    if (!href.startsWith("/"))
+        return href;
+    const hashAt = href.indexOf("#");
+    const path = (hashAt === -1 ? href : href.slice(0, hashAt)).replace(/^\/+|\/+$/g, "");
+    const hash = hashAt === -1 ? "" : href.slice(hashAt);
+    if (!ctx.slugs || !ctx.pageSlug)
+        return href;
+    // `/rest_api/objects/index#frag` names the page emitted as `rest_api/objects.md`
+    // — 76 of 81 links MkDocs reported "left as is" on the OpenShift subset were
+    // this shape. Try the stripped form too.
+    const candidates = [
+        path,
+        path ? `${path}/index` : "index",
+        path.replace(/\.md$/, ""),
+        path.replace(/\/index$/, ""),
+    ];
+    const slug = candidates.find((c) => ctx.slugs.has(c));
+    if (!slug)
+        return href;
+    return `${relativeToPage(`${slug}.md`)}${hash}`;
+}
+/** `/images/x.png` → `../images/x.png` relative to the emitted file. */
+function mkdocsAssetPath(src) {
+    if (!src || /^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//") || !src.startsWith("/")) {
+        return src;
+    }
+    if (!ctx.pageSlug)
+        return src;
+    return relativeToPage(src.replace(/^\/+/, ""));
+}
+/**
+ * Adapt raw HTML for MkDocs: relative asset paths, and the AsciiDoc
+ * converter's admonition-in-a-table-cell convention rewritten to Material's
+ * own admonition markup.
+ *
+ * `adoc2md` emits an admonition inside a table cell as
+ * `<dl class="db-admonition db-admonition-important"><dt>Important</dt><dd>…</dd></dl>`,
+ * because a `!!!` block cannot live inside a raw HTML cell. The Astro
+ * scaffold styles that class; MkDocs has never heard of it, so the 354 such
+ * blocks in the OpenShift corpus rendered as plain definition lists — the
+ * word "Important" as a term, the warning as its definition, no box. Content
+ * intact, signal gone. Material's admonition HTML is stable and documented,
+ * so emit that instead.
+ */
+function relativizeHtmlAssets(html) {
+    let out = html;
+    if (out.includes('db-admonition')) {
+        out = out.replace(/<dl class="db-admonition(?:\s+db-admonition-([a-z]+))?"[^>]*>\s*<dt>([^<]*)<\/dt>\s*<dd>([\s\S]*?)<\/dd>\s*<\/dl>/g, (_m, kind, title, body) => {
+            const raw = (kind || title || "note").toLowerCase();
+            const type = ADMONITION_ALIASES[raw] ?? raw;
+            const inner = /^\s*<(p|ul|ol|pre|div|table)\b/.test(body) ? body : `<p>${body}</p>`;
+            return `<div class="admonition ${type}"><p class="admonition-title">${title.trim() || type}</p>${inner}</div>`;
+        });
+    }
+    if (!ctx.pageSlug)
+        return out;
+    // src / poster / href-to-a-file, either quote style; srcset entries too.
+    out = out.replace(/(\s(?:src|poster|href)=)(["'])(\/[^"']+)\2/g, (m, a, q, path) => {
+        if (a.startsWith(" href=") && !/\.[a-z0-9]{2,5}$/i.test(path.split(/[?#]/)[0]))
+            return m;
+        return `${a}${q}${mkdocsAssetPath(path)}${q}`;
+    });
+    out = out.replace(/(\ssrcset=)(["'])([^"']+)\2/g, (_m, a, q, list) => `${a}${q}${list.split(",").map((e) => e.trim().replace(/^\/\S+/, (u) => mkdocsAssetPath(u))).join(", ")}${q}`);
+    return out;
+}
+// ── Prose ───────────────────────────────────────────────
+function proseToMkdocs(node) {
+    if (node.inline)
+        return inlineToMkdocs(node.inline);
+    if (node.html)
+        return htmlToMkdocs(node.html);
+    return "";
+}
+/**
+ * Text-bearing content across all three TreeNode shapes (flat `inline`,
+ * wrapped `prose` child, html-only), via the core's `renderLeaf`.
+ */
+function leafContent(node) {
+    return renderLeaf(node, {
+        inline: inlineToMkdocs,
+        children: (children) => children.map(nodeToMkdocs).filter(Boolean).join("\n\n"),
+        html: htmlToMkdocs,
+        join: "\n\n",
+    });
+}
+function htmlToMkdocs(html) {
+    // stripHtml decodes `&lt;` back to `<`, which would reintroduce the exact
+    // tag-swallow escapeProse exists to prevent. Re-escape after stripping.
+    return stripHtml(inlineHtmlToMarkdown(relativizeHtmlAssets(html), { flatten: true })).replace(/<(?=[A-Za-z/!?])/g, "&lt;");
+}
+function childrenToMkdocs(node) {
+    if (!node.children || node.children.length === 0)
+        return "";
+    return joinBlocks(node.children);
+}
+// ── Headings ────────────────────────────────────────────
+function headingToMkdocs(node) {
+    const level = node.props?.level ?? 1;
+    const hashes = "#".repeat(Math.min(Math.max(level, 1), 6));
+    const text = leafContent(node) || (node.props?.text ?? "");
+    // The authored id first (`{id="…"}`), then the parser's slug. Emitted via
+    // attr_list so cross-references written against the source ids resolve.
+    const id = safeAnchorId((node.props?.id || node.props?.slug || "").trim());
+    const suffix = id ? ` { #${id} }` : "";
+    return `${hashes} ${text.replace(/\n+/g, " ")}${suffix}`;
+}
+// ── Admonitions ─────────────────────────────────────────
+/** Material's admonition vocabulary; anything else keeps its name. */
+const ADMONITION_ALIASES = {
+    caution: "warning",
+    important: "warning",
+    hint: "tip",
+    attention: "warning",
+    error: "danger",
+};
+function rawVariant(node) {
+    return (calloutVariant(node) || "note").toLowerCase();
+}
+function admonitionType(node) {
+    const raw = rawVariant(node);
+    return ADMONITION_ALIASES[raw] ?? raw;
+}
+function admonitionTitle(node, type) {
+    // `summary` is dogsbay-md's alias for a details title. Only when `title` is
+    // ABSENT: `title: null` is an explicit empty title (`!!! note ""`)
+    const title = (node.props?.title !== undefined ? node.props.title : node.props?.summary);
+    if (title === null)
+        return ' ""';
+    if (title === undefined)
+        return "";
+    const raw = rawVariant(node);
+    const autoTitle = raw.charAt(0).toUpperCase() + raw.slice(1);
+    // An aliased type would otherwise show the alias's auto-title ("Warning"
+    // for an `important`), so keep the original word as an explicit title.
+    if (title === autoTitle && raw === type)
+        return "";
+    // Python-Markdown runs inline patterns over the title: raw HTML there was live.
+    return ` "${escapeProse(title.replace(/[\r\n]+/g, " ")).replace(/"/g, "&quot;")}"`;
+}
 function calloutToMkdocs(node) {
-    const variant = node.props?.variant ?? "note";
-    const title = node.props?.title;
-    const inline = node.props?.inline;
-    let opener = "!!!";
-    let line = `${opener} ${variant}`;
-    if (inline)
-        line += ` ${inline}`;
-    line += titleSuffix(variant, title);
-    const inner = childrenToMkdocs(node);
-    if (!inner)
-        return line;
-    return `${line}\n\n${indent(inner, 4)}`;
+    const type = admonitionType(node);
+    const inlineMod = node.props?.inline;
+    let line = `!!! ${type}`;
+    if (inlineMod)
+        line += ` ${inlineMod}`;
+    line += admonitionTitle(node, type);
+    const inner = bodyContent(node);
+    return inner ? `${line}\n\n${indent(inner, 4)}` : line;
+}
+/** Block children when present; an html-only body otherwise, so it is not lost. */
+function bodyContent(node) {
+    return childrenToMkdocs(node) || (node.children?.length ? "" : leafContent(node));
 }
 function detailsToMkdocs(node) {
-    const variant = node.props?.variant ?? "note";
-    const title = node.props?.title;
+    const type = admonitionType(node);
     const open = node.props?.open;
-    const opener = open ? "???+" : "???";
-    let line = `${opener} ${variant}`;
-    line += titleSuffix(variant, title);
-    const inner = childrenToMkdocs(node);
-    if (!inner)
-        return line;
-    return `${line}\n\n${indent(inner, 4)}`;
+    let line = `${open ? "???+" : "???"} ${type}`;
+    line += admonitionTitle(node, type);
+    const inner = bodyContent(node);
+    return inner ? `${line}\n\n${indent(inner, 4)}` : line;
 }
+// ── Tabs ────────────────────────────────────────────────
 function tabsToMkdocs(node) {
     if (!node.children)
         return "";
-    return node.children.map(nodeToMkdocs).join("\n\n");
+    return node.children.map(tabToMkdocs).filter(Boolean).join("\n\n");
 }
 function tabToMkdocs(node) {
-    const title = node.props?.title ?? "Tab";
-    const inner = childrenToMkdocs(node);
-    if (!inner)
-        return `=== "${title}"`;
-    return `=== "${title}"\n\n${indent(inner, 4)}`;
+    const title = node.props?.title ||
+        node.props?.label ||
+        node.props?.value ||
+        "Tab";
+    const inner = bodyContent(node);
+    const head = `=== "${escapeProse(title.replace(/[\r\n]+/g, " ")).replace(/"/g, "&quot;")}"`;
+    return inner ? `${head}\n\n${indent(inner, 4)}` : head;
 }
+// ── Code ────────────────────────────────────────────────
 function codeToMkdocs(node) {
-    const lang = node.props?.lang ?? "";
-    const code = (node.props?.code ?? "").replace(/\n$/, "");
-    const fence = node.props?.fence ?? "```";
-    return `${fence}${lang}\n${code}\n${fence}`;
+    // Parser: `props.language` + `node.html`; importers: `props.lang` + `props.code`.
+    const lang = node.props?.lang || node.props?.language || "";
+    const code = (node.props?.code ?? node.html ?? "").replace(/\n$/, "");
+    // One line: a newline in the title ended the fence's opening line.
+    const title = node.props?.title?.replace(/[\r\n]+/g, " ").replace(/`/g, "'");
+    const highlights = node.props?.highlights;
+    const fence = pickCodeFence(code);
+    const meta = [];
+    // superfences writes the title into the page's HTML unescaped.
+    if (title)
+        meta.push(`title="${htmlText(title)}"`);
+    if (highlights)
+        meta.push(`hl_lines="${highlights.replace(/[^0-9 ,-]/g, "").replace(/,/g, " ")}"`);
+    const info = [lang || (meta.length ? "text" : ""), ...meta].filter(Boolean).join(" ");
+    return `${fence}${info}\n${code}\n${fence}`;
 }
 function diagramToMkdocs(node) {
     const lang = node.props?.lang ?? "mermaid";
-    const code = (node.props?.code ?? "").replace(/\n$/, "");
-    return `\`\`\`${lang}\n${code}\n\`\`\``;
+    const code = (node.props?.code ?? node.html ?? "").replace(/\n$/, "");
+    const fence = pickCodeFence(code);
+    return `${fence}${lang.replace(/[^\w+#.-]/g, "")}\n${code}\n${fence}`;
 }
-function referencesToMkdocs(node) {
-    const entries = (node.props?.entries ?? []);
-    return entries
-        .map((e) => {
-        let line = `[${e.label}]: ${e.href}`;
-        if (e.title)
-            line += ` "${e.title}"`;
-        return line;
-    })
-        .join("\n");
+function mathBlockToMkdocs(node) {
+    const latex = (node.props?.latex ?? node.props?.content ?? node.html ?? "").trim();
+    return `$$\n${markdownLatex(latex)}\n$$`;
 }
-function annotationListToMkdocs(node) {
-    return childrenToMkdocs(node);
+function collectRows(node) {
+    const out = { header: [], body: [] };
+    for (const child of node.children ?? []) {
+        if (child.type === "thead") {
+            for (const tr of child.children ?? [])
+                if (tr.type === "tr")
+                    out.header.push(tr.children ?? []);
+        }
+        else if (child.type === "tbody") {
+            for (const tr of child.children ?? [])
+                if (tr.type === "tr")
+                    out.body.push(tr.children ?? []);
+        }
+        else if (child.type === "tr") {
+            const cells = child.children ?? [];
+            if (out.body.length === 0 && out.header.length === 0 && cells.some((c) => c.type === "th")) {
+                out.header.push(cells);
+            }
+            else {
+                out.body.push(cells);
+            }
+        }
+    }
+    return out;
 }
-function headingToMkdocs(node) {
-    const level = node.props?.level ?? 1;
-    const hashes = "#".repeat(level);
-    const text = childrenToMkdocs(node);
-    return `${hashes} ${text}`;
+const BLOCK_HTML = /<(ul|ol|p|pre|table|dl|div|blockquote|h[1-6])\b/i;
+/** Does this cell hold something a single pipe-table line cannot? */
+function isBlockCell(cell) {
+    const kids = cell.children ?? [];
+    if (kids.length > 1)
+        return true;
+    if (kids.some((k) => !["paragraph", "prose"].includes(k.type)))
+        return true;
+    if (cell.props?.colspan > 1 || cell.props?.rowspan > 1)
+        return true;
+    // An html-only cell carrying block markup: stripHtml would glue its words.
+    const html = leafHtml(cell);
+    return !!html && BLOCK_HTML.test(html);
 }
-function blockquoteToMkdocs(node) {
-    const inner = childrenToMkdocs(node);
-    return inner
-        .split("\n")
-        .map((line) => (line ? `> ${line}` : ">"))
-        .join("\n");
+function hasBlockCells(rows) {
+    return rows.some((row) => row.some(isBlockCell));
+}
+/**
+ * GFM pipe table when every cell is a single line of inline content;
+ * otherwise an HTML table whose cells are processed as Markdown
+ * (`md_in_html`), so a list or code block inside a cell survives instead of
+ * being flattened onto one line.
+ */
+function tableToMkdocs(node) {
+    const rows = collectRows(node);
+    const all = [...rows.header, ...rows.body];
+    if (all.length === 0)
+        return "";
+    if (hasBlockCells(all))
+        return htmlTableToMkdocs(rows);
+    const text = (cells) => cells.map((c) => (leafContent(c) || "").replace(/\s*\n\s*/g, " ").replace(/\|/g, "\\|").trim());
+    const header = rows.header.length ? text(rows.header[0]) : text(all[0]);
+    const body = (rows.header.length ? rows.body : all.slice(1)).map(text);
+    const cols = Math.max(header.length, ...body.map((r) => r.length));
+    const widths = Array.from({ length: cols }, (_, i) => Math.max(3, header[i]?.length ?? 0, ...body.map((r) => r[i]?.length ?? 0)));
+    const line = (cells) => `| ${Array.from({ length: cols }, (_, i) => (cells[i] ?? "").padEnd(widths[i])).join(" | ")} |`;
+    return [
+        line(header),
+        `| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`,
+        ...body.map(line),
+    ].join("\n");
+}
+/**
+ * md_in_html descends only into elements that THEMSELVES carry a `markdown`
+ * attribute, so `<table markdown>` with bare `<tbody>`/`<tr>` never reaches
+ * the cell: `<td markdown="block">` was emitted and its list rendered as the
+ * literal text `- a - b`. Every wrapper on the way down carries the
+ * attribute. Cells with block content are `markdown="block"`; one-line cells
+ * are `markdown="span"` so a header is not wrapped in `<p>`. A cell whose
+ * content is block HTML from the importer is passed through raw.
+ */
+function htmlTableToMkdocs(rows) {
+    const cell = (c, tag) => {
+        const attrs = [];
+        const colspan = c.props?.colspan;
+        const rowspan = c.props?.rowspan;
+        if (colspan && colspan > 1)
+            attrs.push(` colspan="${colspan}"`);
+        if (rowspan && rowspan > 1)
+            attrs.push(` rowspan="${rowspan}"`);
+        const html = leafHtml(c);
+        if (!c.children?.length && !c.inline?.length && html && BLOCK_HTML.test(html)) {
+            return `<${tag}${attrs.join("")}>${relativizeHtmlAssets(html)}</${tag}>`;
+        }
+        const block = isBlockCell(c);
+        const body = block ? (childrenToMkdocs(c) || leafContent(c)) : (leafContent(c) || childrenToMkdocs(c)).replace(/\s*\n\s*/g, " ");
+        return block
+            ? `<${tag} markdown="block"${attrs.join("")}>\n${body}\n</${tag}>`
+            : `<${tag} markdown="span"${attrs.join("")}>${body}</${tag}>`;
+    };
+    const tr = (cells, tag) => `<tr markdown>\n${cells.map((c) => cell(c, c.type === "th" ? "th" : tag)).join("\n")}\n</tr>`;
+    const parts = ["<table markdown>"];
+    if (rows.header.length)
+        parts.push(`<thead markdown>\n${rows.header.map((r) => tr(r, "th")).join("\n")}\n</thead>`);
+    if (rows.body.length)
+        parts.push(`<tbody markdown>\n${rows.body.map((r) => tr(r, "td")).join("\n")}\n</tbody>`);
+    parts.push("</table>");
+    return parts.join("\n");
+}
+// ── Lists ───────────────────────────────────────────────
+/** Python-Markdown needs FOUR-space continuation for nested block content. */
+function listItemBlock(marker, text) {
+    const lines = text.split("\n");
+    const pad = " ".repeat(Math.max(4, marker.length));
+    // A fence on the marker line is not a fence to the superfences
+    // preprocessor — the whole block collapsed to an inline code span. Start a
+    // fence-first (or table-first) item on the line AFTER the marker.
+    if (/^(`{3,}|~{3,}|<table\b|<div\b|\|)/.test(lines[0] ?? "")) {
+        // A bare marker renders as a paragraph containing "-"; an empty HTML
+        // comment is invisible and gives the item a first line to hang on.
+        return [`${marker}<!-- -->`, "", ...lines.map((l) => (l ? `${pad}${l}` : l))].join("\n");
+    }
+    const first = `${marker}${lines[0] ?? ""}`;
+    const rest = lines.slice(1).map((l) => (l ? `${pad}${l}` : l));
+    return [first, ...rest].join("\n");
 }
 function orderedListToMkdocs(node) {
     if (!node.children)
         return "";
-    return node.children
-        .map((child, i) => {
-        const text = nodeToMkdocs(child);
-        return `${i + 1}. ${text}`;
-    })
-        .join("\n");
+    const start = listStart(node) ?? 1;
+    const items = node.children.map((child, i) => listItemBlock(`${start + i}. `, nodeToMkdocs(child)));
+    return items.join(itemSeparator(node));
 }
 function unorderedListToMkdocs(node) {
     if (!node.children)
         return "";
-    return node.children
-        .map((child) => {
-        const text = nodeToMkdocs(child);
-        return `- ${text}`;
-    })
+    const items = node.children.map((child) => listItemBlock("- ", nodeToMkdocs(child)));
+    return items.join(itemSeparator(node));
+}
+/**
+ * Loose lists need a blank line between items. Loose means an item carries a
+ * block beyond its own text — NOT merely "has children": the wrapped shape
+ * (every HTML-derived importer, the mkdocs walker) puts the item text in a
+ * single paragraph child, and treating that as loose put a `<p>` inside
+ * every `<li>` on a mkdocs → mkdocs round trip.
+ */
+function itemSeparator(list) {
+    const loose = (list.children ?? []).some((li) => {
+        const kids = li.children ?? [];
+        if (kids.length === 0)
+            return false;
+        if (li.inline?.length)
+            return true;
+        return kids.length > 1 || !["paragraph", "prose"].includes(kids[0].type);
+    });
+    return loose ? "\n\n" : "\n";
+}
+function listItemToMkdocs(node) {
+    const parts = [];
+    const checked = node.props?.checked;
+    const box = checked === undefined ? "" : checked ? "[x] " : "[ ] ";
+    if (node.inline && node.inline.length > 0) {
+        parts.push(box + escapeBlockStart(inlineToMkdocs(node.inline)));
+    }
+    if (node.children) {
+        const kids = node.children.map(nodeToMkdocs).filter(Boolean);
+        // A leading paragraph child IS the item text: it goes on the marker line,
+        // and the checkbox goes with it — `- [ ]` alone on the marker line renders
+        // as the literal characters.
+        if (parts.length === 0 && kids.length && node.children[0].type === "paragraph") {
+            parts.push(box + kids[0]);
+            parts.push(...joinBlocksRendered(node.children.slice(1), kids.slice(1)));
+        }
+        else {
+            parts.push(...joinBlocksRendered(node.children, kids));
+        }
+    }
+    else if (box && parts.length === 0) {
+        parts.push(box.trimEnd());
+    }
+    return parts.filter(Boolean).join("\n\n");
+}
+/** Already-rendered siblings, with the adjacent-list separator applied. */
+function joinBlocksRendered(nodes, rendered) {
+    const out = [];
+    let prev;
+    nodes.forEach((n, i) => {
+        const text = rendered[i];
+        if (!text)
+            return;
+        if (prev && ((LIST_TYPES.has(prev.type) && LIST_TYPES.has(n.type)) || (prev.type === "tabs" && n.type === "tabs")))
+            out.push("<!-- -->");
+        out.push(text);
+        prev = n;
+    });
+    return out;
+}
+// ── Definition lists (native: def_list) ─────────────────
+function deflistToMkdocs(node) {
+    if (!node.children?.length)
+        return "";
+    const out = [];
+    for (const child of node.children) {
+        if (child.type === "dt") {
+            out.push(escapeBlockStart(leafContent(child).replace(/\n+/g, " ").trim()));
+            continue;
+        }
+        if (child.type === "dd") {
+            const body = (childrenToMkdocs(child) || leafContent(child)).trim();
+            const lines = body.split("\n");
+            const first = `:   ${lines[0] ?? ""}`;
+            const rest = lines.slice(1).map((l) => (l ? `    ${l}` : l));
+            out.push([first, ...rest].join("\n"));
+            continue;
+        }
+        const other = nodeToMkdocs(child).trim();
+        if (other)
+            out.push(other);
+    }
+    // Term / definition pairs are adjacent; a blank line separates entries.
+    return out
+        .map((block, i) => (block.startsWith(":   ") || i === 0 ? block : `\n${block}`))
         .join("\n");
 }
+// ── Steps → ordered list ────────────────────────────────
+function stepsToMkdocs(node) {
+    if (!node.children)
+        return "";
+    report("steps", "steps rendered as an ordered list (MkDocs has no steps component)");
+    const items = node.children.map((child, i) => {
+        const title = (child.inline && child.inline.length ? inlineToMkdocs(child.inline) : "") ||
+            child.props?.title ||
+            "";
+        const body = childrenToMkdocs(child);
+        const text = title ? (body ? `**${title}**\n\n${body}` : `**${title}**`) : body;
+        return listItemBlock(`${i + 1}. `, text);
+    });
+    return items.join("\n\n");
+}
+// ── Cards (Material grid cards) ─────────────────────────
+function cardToMkdocs(node) {
+    const title = escapeProse(node.props?.title || "");
+    const raw = node.props?.href;
+    const href = raw && isSafeHref(raw) ? raw : undefined;
+    if (raw && !href)
+        report("card", `unsafe link target dropped (${raw.slice(0, 40)})`);
+    const body = childrenToMkdocs(node) || escapeProse(node.props?.description || "");
+    const parts = [];
+    if (title)
+        parts.push(`**${title}**`);
+    if (body)
+        parts.push(body);
+    if (href)
+        parts.push(`[:octicons-arrow-right-24: ${title || "Open"}](${markdownDestination(mkdocsHref(href))})`);
+    return parts.join("\n\n");
+}
+function cardsToMkdocs(node) {
+    if (!node.children?.length)
+        return "";
+    const items = node.children.map((c) => listItemBlock("- ", nodeToMkdocs(c)));
+    return `<div class="grid cards" markdown>\n\n${items.join("\n\n")}\n\n</div>`;
+}
+// ── Misc blocks ─────────────────────────────────────────
 function htmlContainerToMkdocs(node) {
     const tag = node.props?.tag ?? "div";
     const attrs = node.props?.attrs ?? {};
     const attrStr = Object.entries(attrs)
-        .map(([k, v]) => (v ? ` ${k}="${v}"` : ` ${k}`))
+        .filter(([k]) => /^[A-Za-z_:][\w:.-]*$/.test(k) && !/^on/i.test(k))
+        .map(([k, v]) => (v ? ` ${k}="${htmlText(v)}"` : ` ${k}`))
         .join("");
     const inner = childrenToMkdocs(node);
     return `<${tag}${attrStr} markdown>\n\n${inner}\n\n</${tag}>`;
 }
-function childrenToMkdocs(node) {
-    if (!node.children || node.children.length === 0)
-        return "";
-    return node.children.map(nodeToMkdocs).join("\n\n");
+function referencesToMkdocs(node) {
+    const entries = (node.props?.entries ?? []);
+    return entries
+        .filter((e) => isSafeHref(e.href))
+        .map((e) => `[${String(e.label).replace(/[\[\]\n]/g, "")}]: ${markdownDestination(mkdocsHref(e.href))}${linkTitle(e.title)}`)
+        .join("\n");
 }
-function titleSuffix(variant, title) {
-    if (title === null)
-        return ' ""';
-    if (title === undefined)
-        return "";
-    const autoTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
-    if (title === autoTitle)
+function youtubeToMkdocs(node) {
+    const id = String(node.props?.id || node.props?.videoId || "").replace(/[^\w-]/g, "");
+    const title = htmlText(node.props?.title ?? "Video");
+    return `<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/${id}" title="${title}" frameborder="0" allowfullscreen></iframe>`;
+}
+function footnoteDefToMkdocs(node) {
+    const label = footnoteLabel(String(node.props?.label ?? "1"));
+    const content = node.inline && node.inline.length > 0 ? inlineToMkdocs(node.inline) : childrenToMkdocs(node);
+    const lines = content.split("\n");
+    return [`[^${label}]: ${lines[0] ?? ""}`, ...lines.slice(1).map((l) => (l ? `    ${l}` : l))].join("\n");
+}
+// ── API nodes ───────────────────────────────────────────
+function apiSymbolToMkdocs(node) {
+    const name = node.props?.name ?? "";
+    const kind = node.props?.kind ?? "class";
+    const hashes = "#".repeat(node.type === "api-class" ? 3 : 4);
+    const sig = node.props?.signature ?? "";
+    const basesRaw = node.props?.bases;
+    const bases = Array.isArray(basesRaw) ? basesRaw.join(", ") : basesRaw;
+    const parts = [`${hashes} ${escapeProse(kind)} ${codeSpan(name)}`];
+    if (bases)
+        parts.push(`Bases: ${codeSpan(bases)}`);
+    if (sig) {
+        const fence = pickCodeFence(sig);
+        parts.push(`${fence}python\n${sig}\n${fence}`);
+    }
+    const inner = childrenToMkdocs(node);
+    if (inner)
+        parts.push(inner);
+    return parts.join("\n\n");
+}
+function apiParamsToMkdocs(node) {
+    const params = (node.props?.params ?? []);
+    if (params.length === 0)
         return "";
-    return ` "${title}"`;
+    const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const rows = params.map((p) => {
+        let desc = p.docHtml || "";
+        if (!desc && p.doc)
+            desc = `<p>${esc(p.doc)}</p>`;
+        if (!desc && p.description)
+            desc = `<p>${esc(p.description)}</p>`;
+        const meta = [];
+        if (p.type)
+            meta.push(`<strong>TYPE:</strong> <code>${esc(p.type)}</code>`);
+        if (p.default != null)
+            meta.push(`<strong>DEFAULT:</strong> <code>${esc(String(p.default))}</code>`);
+        if (p.required)
+            meta.push("<strong>REQUIRED</strong>");
+        const metaHtml = meta.length ? `<p>${meta.join(" &nbsp;·&nbsp; ")}</p>` : "";
+        return `<tr><td><code>${esc(p.name)}</code></td><td>${desc}${metaHtml}</td></tr>`;
+    });
+    return ["<table>", "<thead><tr><th>PARAMETER</th><th>DESCRIPTION</th></tr></thead>", "<tbody>", ...rows, "</tbody>", "</table>"].join("\n");
 }
-function indent(text, spaces) {
-    const prefix = " ".repeat(spaces);
-    return text
-        .split("\n")
-        .map((line) => (line ? `${prefix}${line}` : line))
-        .join("\n");
+function apiDocToMkdocs(node) {
+    const html = node.props?.html ?? "";
+    return html ? htmlToMkdocs(html) : childrenToMkdocs(node);
+}
+function apiSourceToMkdocs(node) {
+    const code = node.props?.code ?? "";
+    const file = node.props?.file ?? "";
+    const line = node.props?.line;
+    const parts = [];
+    if (file)
+        parts.push(`*Source: ${codeSpan(line ? `${file}:${line}` : file)}*`);
+    if (code)
+        parts.push(`\`\`\`python\n${code.replace(/\n$/, "")}\n\`\`\``);
+    else {
+        const inner = childrenToMkdocs(node);
+        if (inner)
+            parts.push(inner);
+    }
+    return parts.join("\n\n");
+}
+// ── Nav helpers shared with the project emitter ─────────
+/** Normalise an href or slug to the slug form pages are keyed by. */
+export function hrefToSlugKey(href) {
+    return href
+        .replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "")
+        .replace(/[?#].*$/, "")
+        .replace(/^\/+|\/+$/g, "")
+        .replace(/\.md$/, "");
 }
-//# sourceMappingURL=to-mkdocs.js.map