@dogsbay/format-rst 0.2.0-beta.114 → 0.2.0-beta.116

package/dist/transform.js

@@ -15,7 +15,9 @@
  * See plans/format-rst.md for the full node→Dogsbay-MD mapping.
  */
 import { parseDocument } from "htmlparser2";
+import { embeddedSpecRefs, resolveEmbeddedSpec } from "@dogsbay/format-openapi/embed";
 import { stringify as stringifyYaml } from "yaml";
+import { dogsbayMdToTree, slugifyHeadingText, treeToDogsbayMd } from "@dogsbay/format-dogsbay-md";
 // NOTE: guard on the node's `.type` string, never `instanceof`. htmlparser2
 // builds the tree with its own bundled copy of domhandler, which may be a
 // different module instance than the one we import — `instanceof Element`
@@ -52,7 +54,7 @@ export function docutilsXmlToDogsbayMd(xml, opts = {}) {
     const root = findElement(doc, "document");
     const ledger = [];
     if (!root)
-        return { markdown: "", ledger };
+        return { markdown: "", generated: [], openapiSpecs: [], ledger };
     // Sphinx omits the `title=` attr on <document>; the H1 is the first
     // section's <title>. Plain docutils sets `title=`.
     const title = root.attribs?.title ?? firstSectionTitle(root);
@@ -61,11 +63,26 @@ export function docutilsXmlToDogsbayMd(xml, opts = {}) {
     // Plain docutils puts the H1 in `<document title><title>…`; start at
     // depth 1. Sphinx wraps the whole doc in a top `<section>` whose title
     // is the H1, so start at 0 and let that section bump it to 1.
+    // This doc's own anchors, else the corpus index. Not a merged copy: copying
+    // the index per doc made a corpus quadratic (8,000 docs: 15 s of copying).
+    const own = sectionAnchors(root);
+    const anchorOf = (doc, id) => (doc === docPath ? own.get(id) : opts.anchors?.get(doc)?.get(id));
     const ctx = {
         ledger,
         depth: root.attribs?.title ? 1 : 0,
         docDir,
         hrefPrefix: opts.hrefPrefix ?? "",
+        docPath,
+        anchorOf,
+        meta: {},
+        buildDirs: (Array.isArray(opts.buildDir) ? opts.buildDir : opts.buildDir ? [opts.buildDir] : []).filter(Boolean),
+        srcDir: opts.srcDir,
+        extraDirs: opts.extraDirs ?? [],
+        staticDirs: opts.staticDirs ?? [],
+        docname: opts.docname ?? docPath,
+        generated: new Set(),
+        openapiSpecs: new Set(),
+        anchorIds: new Set(),
     };
     // The root `<document>`'s own `<title>` is the H1; its remaining children
     // are the body. Section titles below get depth+1.
@@ -73,16 +90,151 @@ export function docutilsXmlToDogsbayMd(xml, opts = {}) {
     const md = blocks
         .filter((b) => b.trim() !== "")
         .join("\n\n")
+        // A break left outside a line block is a space (with any around it).
+        .replace(/[ \t]*\u0000BR\u0000[ \t]*/g, " ")
         .replace(/\n{3,}/g, "\n\n")
         .trim();
-    return { markdown: md + "\n", title, ledger };
+    return {
+        markdown: md + "\n",
+        title,
+        description: ctx.meta.description,
+        generated: [...ctx.generated].sort(),
+        openapiSpecs: [...ctx.openapiSpecs].sort(),
+        ledger,
+    };
+}
+/**
+ * A raw HTML block that embeds an API viewer → `:::openapi{spec="/path"}`
+ * per spec found in the source tree. `undefined` when the block is not an
+ * embed (it is handled as raw HTML); `null` when it is one whose spec is not
+ * in the source (ledgered, nothing emitted: the viewer's script is no use).
+ */
+function renderApiViewerEmbed(html, ctx) {
+    const refs = embeddedSpecRefs(html);
+    if (!refs.length)
+        return undefined;
+    const out = [];
+    for (const ref of refs) {
+        const spec = ctx.srcDir
+            ? resolveEmbeddedSpec(ref, { srcDir: ctx.srcDir, docname: ctx.docname, extraDirs: ctx.extraDirs, staticDirs: ctx.staticDirs })
+            : null;
+        // The path goes into a directive attribute: nothing that could end it.
+        if (!spec || !/^[^"{}\\\s<>]+$/.test(spec)) {
+            ctx.ledger.push({
+                construct: "API viewer embed",
+                note: ctx.srcDir ? `spec ${ref} not found in the source — dropped` : `spec ${ref} not looked up (no source dir) — dropped`,
+            });
+            continue;
+        }
+        ctx.openapiSpecs.add(spec);
+        ctx.ledger.push({ construct: "API viewer embed", note: `→ :::openapi from ${spec}` });
+        out.push(`:::openapi{spec="/${spec}"}\n:::`);
+    }
+    return out.length ? out.join("\n\n") : null;
+}
+/** `<a id>` for an id not yet anchored on this page; "" otherwise. */
+function anchorTag(ctx, id) {
+    if (!id || ctx.anchorIds.has(id))
+        return "";
+    ctx.anchorIds.add(id);
+    return `<a id="${escapeAttr(id)}"></a>`;
+}
+/**
+ * A Markdown link or image DESTINATION from content. A `)` would end it
+ * early and let the rest of the path become live markup
+ * (`.. image:: a)<script>…</script>.png` did, in plain mode too); spaces,
+ * angle brackets, quotes and backslashes are encoded the same way.
+ */
+function mdDest(uri) {
+    // encodeURIComponent leaves `(`, `)` and `'` alone: explicit codes.
+    return uri.replace(/[\s<>()"'`\\]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0"));
+}
+/** Sentinel for a `line` nested in inline content: a hard break inside a
+ *  line block, a space anywhere else (a table cell, heading, link text). */
+const LINE_BREAK = "\u0000BR\u0000";
+/** Inline text with its nested-line breaks as spaces, none at the end. */
+function inlineOneLine(t) {
+    const u = t.endsWith(LINE_BREAK) ? t.slice(0, -LINE_BREAK.length) : t;
+    return u.split(LINE_BREAK).join(" ");
+}
+/** Sphinx 7 writes XML booleans as `True`; older docutils as `1`. */
+function isTrue(v) {
+    return v === "1" || v === "True" || v === "true";
+}
+/**
+ * The id a section's heading is given: its first LABEL when it has one
+ * (`ids="rust-plugin craft-parts-rust-plugin"` → the label, which is what
+ * `:ref:` links target and what the author chose), else docutils' id.
+ */
+function sectionHeadingId(section) {
+    const ids = (section.attribs?.ids ?? "").split(/\s+/).filter(Boolean);
+    return ids.length > 1 ? ids[1] : ids[0];
+}
+/** Every section id in one document → its heading id. */
+function sectionAnchors(root) {
+    const map = new Map();
+    const walk = (el) => {
+        for (const c of elementChildren(el)) {
+            if (c.tagName === "section") {
+                const id = sectionHeadingId(c);
+                if (id)
+                    for (const any of (c.attribs?.ids ?? "").split(/\s+/).filter(Boolean))
+                        map.set(any, id);
+            }
+            walk(c);
+        }
+    };
+    walk(root);
+    return map;
+}
+/** Section anchors of one XML document, for the corpus pre-pass. */
+export function collectSectionAnchors(xml) {
+    const root = findElement(parseDocument(xml, { xmlMode: true }), "document");
+    return root ? sectionAnchors(root) : new Map();
+}
+const SLUG_SKIPPED = new Set(["literal", "reference", "footnote_reference", "citation_reference", "image", "target"]);
+/** A title's text as the Dogsbay slugger reads it: code spans do not count,
+ *  unless nothing else is left. */
+function plainTitleText(title) {
+    const walk = (el) => {
+        let s = "";
+        for (const c of el.children) {
+            if (isTextNode(c))
+                s += textData(c);
+            // The slugger reads text nodes only: a code span, a link's label, a
+            // footnote mark or an image contribute nothing to the heading's slug.
+            else if (isTag(c) && !SLUG_SKIPPED.has(c.tagName))
+                s += walk(c);
+        }
+        return s;
+    };
+    const text = walk(title).trim();
+    return slugifyHeadingText(text) ? text : textContent(title).trim();
 }
 // ── Block level ────────────────────────────────────────────────────────────
+/** Blocks that place their own ids (or have none worth keeping). */
+const OWN_ANCHORS = new Set(["section", "footnote", "citation", "topic", "desc", "raw", "comment", "substitution_definition"]);
 function renderBlocks(nodes, ctx) {
     const out = [];
     for (const n of nodes) {
         if (!isTag(n))
             continue; // whitespace text between blocks — ignore
+        // An explicit target (`.. _name:`) on a block other than a section puts
+        // its id on that block; keep it as an anchor. Auto ids (`id1`) carry no
+        // `names` and are never linked, so they are left out.
+        // A label that cannot attach to the next block (something stands between
+        // them, such as a substitution definition) stays a `<target>` holding the
+        // id itself; it is still a link target. One with `refuri` is an external
+        // hyperlink target, not an anchor.
+        const standaloneTarget = n.tagName === "target" && !n.attribs?.refuri;
+        // A sphinx-needs need renders as a table whose ids ARE the need's ID
+        // (`SP_INT`), with no `names`; links to the need target it.
+        const needTable = n.tagName === "table" && (n.attribs?.classes ?? "").split(/\s+/).includes("need");
+        if (!OWN_ANCHORS.has(n.tagName) && (n.tagName !== "target" || standaloneTarget) && n.attribs?.ids && (n.attribs?.names || needTable)) {
+            const tags = n.attribs.ids.split(/\s+/).filter(Boolean).map((id) => anchorTag(ctx, id)).join("");
+            if (tags)
+                out.push(tags);
+        }
         const s = renderBlock(n, ctx);
         if (s != null)
             out.push(s);
@@ -96,7 +248,33 @@ function renderBlock(el, ctx) {
             return `${"#".repeat(Math.min(ctx.depth, 6))} ${renderInline(kids(el), ctx).trim()}`;
         case "section": {
             const child = { ...ctx, depth: ctx.depth + 1 };
-            return renderBlocks(elementChildren(el), child).join("\n\n");
+            const id = sectionHeadingId(el);
+            const children = elementChildren(el);
+            const titleEl = children[0]?.tagName === "title" ? children[0] : undefined;
+            const parts = [];
+            if (titleEl) {
+                let heading = renderBlock(titleEl, child) ?? "";
+                // The heading carries the id links target; written out only when it
+                // differs from the slug the site derives from the heading text.
+                const derived = slugifyHeadingText(plainTitleText(titleEl));
+                if (id && id !== derived)
+                    heading += ` {#${id}}`;
+                if (id)
+                    ctx.anchorIds.add(id);
+                // Sphinx's HTML carries EVERY id of a section, and its ¶ permalink
+                // uses the first, so `/page/#steps` links shared from the old site
+                // target ids the heading no longer has. Keep them as anchors.
+                // After the heading, not before: the layout looks for an H1 as the
+                // page's FIRST node, and an anchor ahead of it made every labelled
+                // page render its title twice.
+                const extra = (el.attribs?.ids ?? "").split(/\s+/).filter((x) => x && x !== id && !(x === derived && id === derived));
+                parts.push(heading);
+                const extraTags = extra.map((x) => anchorTag(ctx, x)).join("");
+                if (extraTags)
+                    parts.push(extraTags);
+            }
+            parts.push(...renderBlocks(titleEl ? children.slice(1) : children, child));
+            return parts.join("\n\n");
         }
         case "paragraph":
             return renderInline(kids(el), ctx).trim();
@@ -123,19 +301,115 @@ function renderBlock(el, ctx) {
         }
         case "line_block":
             // rST line block — significant line breaks; join with hard breaks.
-            return elementChildren(el)
-                .filter((c) => c.tagName === "line")
-                .map((line) => renderInline(kids(line), ctx).trim())
-                .join("\\\n");
+            {
+                // Every line (nested `line`s too) on its own line; empty ones dropped
+                // (a need with no status or tags left a lone `\`); each escaped so a
+                // line cannot start a heading or a list.
+                const lines = elementChildren(el)
+                    .filter((c) => c.tagName === "line")
+                    .flatMap((line) => renderInline(kids(line), ctx).split(LINE_BREAK))
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                    .map(escapeLineStart);
+                return lines.length ? lines.join("\\\n") : null;
+            }
         case "container":
             return renderContainer(el, ctx);
         case "compound":
-            // Sphinx toctree renders as a <compound toctree-wrapper> in the body;
-            // it's navigation (extracted separately by loaders/sphinx.ts), not
-            // page content — drop it here. Other compounds render their blocks.
+            // A VISIBLE toctree is page content: Sphinx renders it as a list of
+            // links where it stands (a landing page's list of its children). The
+            // nav comes from the build environment instead (loaders/sphinx.ts);
+            // a `:hidden:` toctree reaches the XML empty and renders nothing.
             if ((el.attribs?.classes ?? "").includes("toctree-wrapper"))
-                return null;
+                return renderToctree(el, ctx);
             return renderBlocks(elementChildren(el), ctx).join("\n\n");
+        case "compact_paragraph":
+            return renderLoose(el, ctx);
+        case "raw": {
+            // An API viewer (Swagger UI, Redoc) drawing a spec in the browser:
+            // dropping the script left the page empty. The spec becomes a
+            // `:::openapi` directive the site build renders.
+            if ((el.attribs?.format ?? "").split(/\s+/).includes("html")) {
+                const embed = renderApiViewerEmbed(textContent(el), ctx);
+                if (embed !== undefined)
+                    return embed;
+            }
+            // Output-format passthrough. Raw HTML is not carried into a migrated
+            // page, but in MyST it often wraps words (`<spellexception>master
+            // </spellexception>`); those are kept as text. Comments and other
+            // formats (LaTeX) are dropped.
+            const text = (el.attribs?.format ?? "").split(/\s+/).includes("html") ? rawHtmlText(el).trim() : "";
+            ctx.ledger.push({
+                construct: `raw ${el.attribs?.format ?? ""}`.trim(),
+                note: text ? "raw HTML — tags dropped, text kept" : "raw output passthrough — dropped",
+            });
+            // Alone on its lines, the text must not start a list or heading.
+            return text ? escapeLineStart(escapeText(text)) : null;
+        }
+        case "plantuml": {
+            // sphinxcontrib-plantuml (sphinx-needs' needflow, needuml, needarch,
+            // needgantt): the XML builder renders no image, so the diagram source
+            // is kept as a code block.
+            const code = (el.attribs?.uml ?? "").replace(/\n$/, "");
+            ctx.ledger.push({ construct: "plantuml", note: "PlantUML diagram kept as source (not rendered)" });
+            if (!code.trim())
+                return null;
+            const fence = pickCodeFence(code);
+            return `${fence}plantuml\n${code}\n${fence}`;
+        }
+        case "mermaid": {
+            // sphinxcontrib-mermaid keeps the diagram source in `code`; the site
+            // renders a mermaid fence.
+            const code = (el.attribs?.code ?? "").replace(/\n$/, "");
+            if (!code.trim())
+                return null;
+            const fence = pickCodeFence(code);
+            return `${fence}mermaid\n${code}\n${fence}`;
+        }
+        case "topic":
+        case "sidebar": {
+            if (tag === "topic" && (el.attribs?.classes ?? "").split(/\s+/).includes("contents")) {
+                // `.. contents::` — the page's own table of contents replaces it.
+                ctx.ledger.push({ construct: "contents", note: "local table of contents — the site's page TOC replaces it" });
+                return null;
+            }
+            const titleEl = elementChildren(el).find((c) => c.tagName === "title");
+            const title = titleEl ? plainText(titleEl) : undefined;
+            const body = elementChildren(el).filter((c) => c.tagName !== "title" && c.tagName !== "subtitle");
+            const inner = renderBlocks(body, ctx).join("\n\n").trim();
+            if (!inner)
+                return null;
+            const fence = ":".repeat(3 + colonDepth(inner));
+            return `${fence}note${title ? `{title="${escapeAttr(title)}"}` : ""}\n${inner}\n${fence}`;
+        }
+        case "footnote":
+        case "citation":
+            return renderFootnote(el, ctx);
+        case "glossary":
+            // Sphinx's wrapper around a definition list whose terms carry the
+            // `term-…` ids `:term:` links point at (renderDefinitionList keeps them).
+            return renderBlocks(elementChildren(el), ctx).join("\n\n") || null;
+        case "rubric":
+            // An informal heading: kept out of the TOC, as Sphinx does.
+            return `**${renderInline(kids(el), ctx).trim()}**`;
+        case "meta":
+            if (el.attribs?.name === "description" && el.attribs?.content) {
+                ctx.meta.description = el.attribs.content.replace(/\s+/g, " ").trim();
+                return null;
+            }
+            ctx.ledger.push({ construct: `meta ${el.attribs?.name ?? ""}`.trim(), note: "page metadata other than description — dropped" });
+            return null;
+        case "Domain":
+            // sphinx-structured-toc (Canonical's starter pack): a landing grid of
+            // named slices, each a list of links.
+            return renderBlocks(elementChildren(el), ctx).join("\n\n") || null;
+        case "Slice": {
+            const items = elementChildren(el)
+                .filter((c) => c.tagName === "SliceItem")
+                .map((c) => `- ${renderInline(kids(c), ctx).trim()}`);
+            const name = el.attribs?.name ? `**${escapeText(el.attribs.name)}**` : "";
+            return [name, items.join("\n")].filter(Boolean).join("\n\n") || null;
+        }
         case "bullet_list":
             return renderList(el, ctx, false);
         case "enumerated_list":
@@ -147,10 +421,12 @@ function renderBlock(el, ctx) {
         case "block_quote":
             return renderBlockQuote(el, ctx);
         case "image":
-            return renderImage(el);
+            return renderImage(el, ctx);
         case "figure":
             return renderFigure(el, ctx);
         case "table":
+        case "NeedtableTable":
+            // sphinx-needs' needtable: a table under its own node names.
             return renderTable(el, ctx);
         case "transition":
             return "---";
@@ -184,10 +460,52 @@ function renderBlock(el, ctx) {
             return null;
         case "literal": // stray block-level literal
             return renderInline([el], ctx).trim();
-        default:
-            ctx.ledger.push({ construct: `<${tag}>`, note: "unmapped docutils node — dropped" });
-            return null;
+        default: {
+            // Never drop what we do not know: render its content and say so.
+            const out = renderLoose(el, ctx);
+            ctx.ledger.push({
+                construct: `<${tag}>`,
+                note: out ? "unmapped node — wrapper dropped, content kept" : "unmapped node with no content — dropped",
+            });
+            return out;
+        }
+    }
+}
+const INLINE_TAGS = new Set([
+    "reference", "inline", "literal", "strong", "emphasis", "title_reference", "math",
+    "footnote_reference", "substitution_reference", "abbreviation", "literal_strong",
+    "literal_emphasis", "pending_xref", "image", "target",
+]);
+/** Content of a node with no mapping: a paragraph when it holds only text
+ *  and inline elements, its blocks otherwise. */
+function renderLoose(el, ctx) {
+    const inlineOnly = kids(el).every((c) => isTextNode(c) ? true : isTag(c) ? INLINE_TAGS.has(c.tagName) : true);
+    const out = inlineOnly
+        ? renderInline(kids(el), ctx).trim()
+        : renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
+    return out || null;
+}
+/** A footnote or citation → `[^id]: text`, matching footnote_reference's `[^refid]`. */
+function renderFootnote(el, ctx) {
+    const id = (el.attribs?.ids ?? "").split(/\s+/).filter(Boolean)[0];
+    const body = renderBlocks(elementChildren(el).filter((c) => c.tagName !== "label"), ctx).join("\n\n").trim();
+    if (!id || !body)
+        return null;
+    const [first, ...rest] = body.split("\n");
+    return [`[^${id}]: ${first}`, ...rest.map((r) => (r ? `    ${r}` : r))].join("\n");
+}
+/** A visible toctree: its caption, then its entries as a list of links. */
+function renderToctree(el, ctx) {
+    const out = [];
+    for (const cp of elementChildren(el).filter((c) => c.tagName === "compact_paragraph")) {
+        const caption = elementChildren(cp).find((c) => c.tagName === "title");
+        if (caption)
+            out.push(`**${renderInline(kids(caption), ctx).trim()}**`);
+        for (const list of elementChildren(cp).filter((c) => c.tagName === "bullet_list")) {
+            out.push(renderList(list, ctx, false));
+        }
     }
+    return out.filter(Boolean).join("\n\n") || null;
 }
 function renderAdmonition(name, el, ctx, title) {
     const inner = renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
@@ -198,7 +516,7 @@ function renderAdmonition(name, el, ctx, title) {
 function renderGenericAdmonition(el, ctx) {
     // `.. admonition:: Custom title` → first <title> child is the title.
     const titleEl = elementChildren(el).find((c) => c.tagName === "title");
-    const title = titleEl ? renderInline(kids(titleEl), ctx).trim() : undefined;
+    const title = titleEl ? plainText(titleEl) : undefined;
     const body = elementChildren(el).filter((c) => c.tagName !== "title");
     const inner = renderBlocks(body, ctx).join("\n\n").trim();
     const attrs = title ? `{title="${escapeAttr(title)}"}` : "";
@@ -210,10 +528,14 @@ function renderCodeBlock(el, title) {
     // the full text content. Language: `language=` attr (Sphinx) or
     // `classes="code <lang>"` (plain docutils).
     const classes = (el.attribs?.classes ?? "").split(/\s+/);
-    const lang = el.attribs?.language ?? classes.find((c) => c && c !== "code") ?? "";
+    // The language is the first word of the fence's info string: a backtick
+    // there makes CommonMark reject the fence (the code turns into live HTML),
+    // and a space would add attributes. Only a plain language name is kept.
+    const rawLang = el.attribs?.language ?? classes.find((c) => c && c !== "code") ?? "";
+    const lang = /^[\w#+.-]+$/.test(rawLang) ? rawLang : "";
     const code = textContent(el).replace(/\n$/, "");
     const fence = pickCodeFence(code);
-    const info = title ? `${lang} title="${escapeAttr(title)}"` : lang;
+    const info = title ? `${lang} title="${fenceTitle(title)}"` : lang;
     return `${fence}${info}\n${code}\n${fence}`;
 }
 /**
@@ -224,15 +546,118 @@ function renderCodeBlock(el, title) {
  */
 function renderContainer(el, ctx) {
     const classes = el.attribs?.classes ?? "";
-    if (classes.includes("literal-block-wrapper") || el.attribs?.literal_block === "1") {
+    switch (el.attribs?.design_component) {
+        case "tab-set":
+            return renderTabSet(el, ctx);
+        case "dropdown":
+            return renderDropdown(el, ctx);
+        case undefined:
+            break;
+        default: {
+            // Other sphinx-design components (grid, card, button): content kept.
+            const out = renderBlocks(elementChildren(el), ctx).join("\n\n").trim() || null;
+            ctx.ledger.push({ construct: `sphinx-design ${el.attribs.design_component}`, note: "layout dropped, content kept" });
+            return out;
+        }
+    }
+    if (classes.split(/\s+/).includes("terminal"))
+        return renderTerminal(el);
+    if (classes.includes("literal-block-wrapper") || isTrue(el.attribs?.literal_block)) {
         const lit = descendant(el, "literal_block");
         const capEl = elementChildren(el).find((c) => c.tagName === "caption");
-        const caption = capEl ? renderInline(kids(capEl), ctx).trim() : undefined;
+        // A title attribute takes plain text: Markdown escapes would show.
+        const caption = capEl ? plainText(capEl) : undefined;
         return lit ? renderCodeBlock(lit, caption) : null;
     }
     const inner = renderBlocks(elementChildren(el), ctx).join("\n\n").trim();
     return inner || null;
 }
+/** sphinx-design `tab-set` → `:::tabs`, each label a term and its content
+ *  the `:` definition. */
+function renderTabSet(el, ctx) {
+    const items = [];
+    for (const item of elementChildren(el).filter((c) => c.attribs?.design_component === "tab-item")) {
+        const labelEl = elementChildren(item).find((c) => c.tagName === "rubric");
+        const label = escapeLineStart(labelEl ? renderInline(kids(labelEl), ctx).trim() : "Tab");
+        const content = elementChildren(item).find((c) => c.attribs?.design_component === "tab-content");
+        const body = content ? renderBlocks(elementChildren(content), ctx).join("\n\n").trim() : "";
+        items.push(definitionItem(label, body || label));
+    }
+    if (!items.length)
+        return null;
+    const inner = items.join("\n\n");
+    const fence = ":".repeat(3 + colonDepth(inner));
+    return `${fence}tabs\n${inner}\n${fence}`;
+}
+/** sphinx-design `dropdown` → `:::details{title}`. */
+function renderDropdown(el, ctx) {
+    const children = elementChildren(el);
+    const titleEl = isTrue(el.attribs?.has_title) ? children.find((c) => c.tagName === "rubric") : undefined;
+    const title = titleEl ? plainText(titleEl) : "Details";
+    const body = renderBlocks(children.filter((c) => c !== titleEl), ctx).join("\n\n").trim();
+    const fence = ":".repeat(3 + colonDepth(body));
+    // `open="true"`, not a bare `open`: a bare attribute parses as "", which
+    // format-astro reads as closed.
+    const open = isTrue(el.attribs?.opened) ? ` open="true"` : "";
+    return `${fence}details{title="${escapeAttr(title)}"${open}}\n${body}\n${fence}`;
+}
+/**
+ * sphinx-terminal → the commands in a `bash` fence, without the prompt (what
+ * the copy button copies), and the output in a `text` fence.
+ */
+function renderTerminal(el) {
+    const out = [];
+    let commands = [];
+    let prompt = "";
+    const flush = () => {
+        if (!commands.length)
+            return;
+        const code = commands.join("\n");
+        const fence = pickCodeFence(code);
+        // The prompt says WHERE to run it (`user@server01:~$`, a root `#`) — a
+        // server how-to switches machines between blocks. Kept as the block's
+        // title, not in the code, so the copy button copies only the command.
+        const title = informativePrompt(prompt) ? ` title="${fenceTitle(prompt)}"` : "";
+        out.push(`${fence}bash${title}\n${code}\n${fence}`);
+        commands = [];
+    };
+    for (const c of elementChildren(el)) {
+        if (c.tagName === "container" && (c.attribs?.classes ?? "").split(/\s+/).includes("input")) {
+            const promptEl = elementChildren(c).find((x) => (x.attribs?.classes ?? "").split(/\s+/).includes("prompt"));
+            const thisPrompt = promptEl ? textContent(promptEl).replace(/\s+/g, " ").trim() : "";
+            if (commands.length && thisPrompt !== prompt)
+                flush();
+            prompt = thisPrompt;
+            const cmd = elementChildren(c).find((x) => (x.attribs?.classes ?? "").split(/\s+/).includes("command"));
+            // sphinx-terminal marks every input line after the first with `> `;
+            // authors use it for several commands, so each becomes its own line.
+            if (cmd)
+                commands.push(textContent(cmd).replace(/\n> /g, "\n"));
+        }
+        else if (c.tagName === "literal_block") {
+            flush();
+            const code = textContent(c).replace(/\n$/, "");
+            if (code.trim()) {
+                const fence = pickCodeFence(code);
+                out.push(`${fence}text\n${code}\n${fence}`);
+            }
+        }
+    }
+    flush();
+    return out.join("\n\n") || null;
+}
+/** sphinx-terminal's defaults; a bare `#` is kept, it says "as root". */
+const UNINFORMATIVE_PROMPTS = ["$", "~$", ">", "user@host:~$"];
+/** A prompt worth showing: a named host or user, a directory, or root.
+ *  sphinx-terminal's defaults (`$`, `~$`, `user@host:~$`) say nothing. */
+function informativePrompt(prompt) {
+    return prompt !== "" && !UNINFORMATIVE_PROMPTS.includes(prompt);
+}
+/** A term and its definition body, in the `:` form tabs use. */
+function definitionItem(term, body) {
+    const [first, ...rest] = body.split("\n");
+    return [`${term}`, `:   ${first}`, ...rest.map((r) => (r ? `    ${r}` : r))].join("\n");
+}
 function renderDoctest(el) {
     const code = textContent(el).replace(/\n$/, "");
     const fence = pickCodeFence(code);
@@ -315,7 +740,22 @@ function renderDesc(el, ctx) {
         const plist = elementChildren(sig).find((c) => c.tagName === "desc_parameterlist");
         const params = plist ? serializeParams(plist) : "";
         const full = `${addname}${shortName}`.trim();
-        return { full, sig: `${full}${plist ? `(${params})` : ""}`.trim() };
+        // The types: an annotation before the name (`class`, `async`), the
+        // return type, and one after it (an attribute's `: NotRequired[int]`, a
+        // default `= None`). Only the name and parameters were kept, which lost
+        // every type on an API page.
+        const kids = elementChildren(sig);
+        const nameAt = kids.findIndex((c) => c.tagName === "desc_name");
+        const flat = (el) => textContent(el).replace(/\s+/g, " ");
+        const prefix = kids.slice(0, Math.max(0, nameAt)).filter((c) => c.tagName === "desc_annotation").map(flat).join("");
+        let suffix = "";
+        for (const c of kids.slice(nameAt + 1)) {
+            if (c.tagName === "desc_returns")
+                suffix += ` -> ${flat(c).trim()}`;
+            else if (c.tagName === "desc_annotation")
+                suffix += flat(c);
+        }
+        return { full, sig: `${prefix}${full}${plist ? `(${params})` : ""}${suffix}`.replace(/\s+/g, " ").trim() };
     };
     const parsed = sigs.map(signatureText);
     const fullName = parsed.find((p) => p.full)?.full ?? "";
@@ -330,7 +770,9 @@ function renderDesc(el, ctx) {
         const id = sig.attribs?.ids?.split(/\s+/)[0];
         if (id && !seenIds.has(id)) {
             seenIds.add(id);
-            parts.push(`<a id="${id}"></a>`);
+            const tag = anchorTag(ctx, id);
+            if (tag)
+                parts.push(tag);
         }
     }
     const content = elementChildren(el).find((c) => c.tagName === "desc_content");
@@ -375,15 +817,27 @@ function renderList(el, ctx, ordered) {
 function renderDefinitionList(el, ctx) {
     const out = [];
     for (const item of elementChildren(el).filter((c) => c.tagName === "definition_list_item")) {
-        const termEl = elementChildren(item).find((c) => c.tagName === "term");
-        const defEl = elementChildren(item).find((c) => c.tagName === "definition");
-        const term = termEl ? renderInline(kids(termEl), ctx).trim() : "";
-        const defBlocks = defEl ? renderBlocks(elementChildren(defEl), ctx) : [];
-        const def = defBlocks.join("\n\n").trim();
-        const [first, ...rest] = def.split("\n");
-        out.push(`${term}\n:   ${first}`);
-        for (const r of rest)
-            out.push(r ? "    " + r : r);
+        // A glossary term carries `ids="term-…"`, the target of `:term:` links,
+        // and one entry can define several terms ("GPO", "Group Policy Object"):
+        // all of them are kept, on one term line.
+        const term = elementChildren(item)
+            .filter((c) => c.tagName === "term")
+            .map((termEl) => {
+            const ids = (termEl.attribs?.ids ?? "").split(/\s+/).filter(Boolean);
+            return ids.map((id) => anchorTag(ctx, id)).join("") + renderInline(kids(termEl), ctx).trim();
+        })
+            .join(", ");
+        // MyST allows several `:` definitions for one term; each is kept (only
+        // the first was, which lost two of three on Ubuntu Server's AI-tools page).
+        const defs = elementChildren(item)
+            .filter((c) => c.tagName === "definition")
+            .map((d) => {
+            const [first, ...rest] = renderBlocks(elementChildren(d), ctx).join("\n\n").trim().split("\n");
+            // Continuation lines indented under the `:` — in ONE string, so a
+            // multi-line definition (a code block) gets no blank lines inside.
+            return [`:   ${first}`, ...rest.map((r) => (r ? `    ${r}` : r))].join("\n");
+        });
+        out.push([term, ...(defs.length ? defs : [":   "])].join("\n"));
     }
     return out.join("\n\n");
 }
@@ -407,17 +861,61 @@ function renderBlockQuote(el, ctx) {
         .map((l) => (l ? `> ${l}` : ">"))
         .join("\n");
 }
-function renderImage(el) {
-    const uri = el.attribs?.uri ?? "";
+function renderImage(el, ctx) {
+    let uri = el.attribs?.uri ?? "";
+    // Sphinx rewrites an image's `uri` relative to the SOURCE ROOT (it keeps
+    // the authored one as `original_uri`, and lists `candidates`); plain
+    // docutils leaves it relative to the document. Only Sphinx sets
+    // `candidates`. Read as page-relative, 45 of Ubuntu Server's images broke.
+    const prefix = ctx.hrefPrefix.replace(/\/$/, "");
+    if (uri.startsWith("/") && el.attribs?.candidates !== undefined) {
+        // An extension may record an ABSOLUTE file path. In the build's output
+        // dir: a file the build generated (sphinx-needs' needbar / needpie),
+        // copied out by the importer. In the source dir: a source image. Anywhere
+        // else: not part of the documentation, and not copied.
+        const under = (dir) => (dir && uri.startsWith(dir.replace(/\/$/, "") + "/") ? uri.slice(dir.replace(/\/$/, "").length + 1) : undefined);
+        const gen = ctx.buildDirs.map(under).find((x) => x !== undefined);
+        const src = under(ctx.srcDir);
+        if (gen !== undefined && !gen.split("/").includes("..")) {
+            ctx.generated.add(gen);
+            uri = `${prefix}/sphinx-generated/${gen}`;
+        }
+        else if (src !== undefined && !src.split("/").includes("..")) {
+            uri = `${prefix}/${src}`;
+        }
+        else if (ctx.buildDirs.length || ctx.srcDir) {
+            ctx.ledger.push({ construct: "image", note: "image outside the documentation source — not copied" });
+            return el.attribs?.alt ? escapeText(el.attribs.alt) : "";
+        }
+    }
+    else if (el.attribs?.candidates !== undefined && uri && !/^[a-z][a-z0-9+.-]*:|^\/|^#/i.test(uri)) {
+        if (uri.startsWith("../")) {
+            // Outside the source root: Sphinx keeps the `..`, and no site path
+            // exists for it. The authored path is kept and the loss ledgered.
+            ctx.ledger.push({ construct: `image ${uri}`, note: "image outside the documentation source — not copied" });
+            uri = el.attribs?.original_uri ?? uri;
+        }
+        else {
+            uri = `${prefix}/${uri}`;
+        }
+    }
     const alt = el.attribs?.alt ?? "";
-    return `![${escapeAlt(alt)}](${uri})`;
+    return `![${escapeAlt(alt)}](${mdDest(uri)})`;
 }
 function renderFigure(el, ctx) {
     const img = elementChildren(el).find((c) => c.tagName === "image");
     const capEl = elementChildren(el).find((c) => c.tagName === "caption");
-    const imgMd = img ? renderImage(img) : "";
+    // A figure around something other than an image (a PlantUML diagram).
+    const body = img
+        ? renderImage(img, ctx)
+        : renderBlocks(elementChildren(el).filter((c) => c.tagName !== "caption" && c.tagName !== "legend"), ctx).join("\n\n");
+    if (!img && !body.trim()) {
+        // sphinx-needs' needflow with the Graphviz engine: Sphinx's XML output
+        // carries only the caption, so the diagram cannot be recovered from it.
+        ctx.ledger.push({ construct: "figure", note: "figure with no content in Sphinx's XML (e.g. a Graphviz needflow) — caption kept" });
+    }
     const cap = capEl ? renderInline(kids(capEl), ctx).trim() : "";
-    return cap ? `${imgMd}\n\n_${cap}_` : imgMd;
+    return [body, cap ? `_${cap}_` : ""].filter((x) => x.trim()).join("\n\n");
 }
 // ── Tables ──────────────────────────────────────────────────────────────────
 function renderTable(el, ctx) {
@@ -439,8 +937,7 @@ function renderTable(el, ctx) {
     const withPipeCaption = (table) => caption ? `${table}\n\n{caption="${captionAttr(caption)}"}` : table;
     // Fall back to an HTML table when any cell spans columns/rows or holds
     // block content a GFM pipe table can't represent.
-    const complex = [...headRows, ...bodyRows].some((r) => elementChildren(r)
-        .filter((c) => c.tagName === "entry")
+    const complex = [...headRows, ...bodyRows].some((r) => entriesOf(r)
         .some((e) => e.attribs?.morecols || e.attribs?.morerows || isBlockCell(e)));
     if (complex)
         return renderHtmlTable(headRows, bodyRows, ctx, caption);
@@ -459,21 +956,38 @@ function renderTable(el, ctx) {
 function captionAttr(text) {
     return text.replace(/"/g, "&quot;").replace(/\n+/g, " ").trim();
 }
+/**
+ * A table a pipe table cannot hold (spans, block content, several
+ * paragraphs in a cell) → Dogsbay MD's HTML table form. Each cell's content
+ * is converted to Dogsbay MD, parsed by the canonical parser, and the table
+ * is serialized by format-dogsbay-md, so the cells are HTML. Markdown inside
+ * an HTML block is not parsed: writing the cells as Markdown showed `name`
+ * with its backticks, `*Getting started*` with its asterisks, and links as
+ * `[text](url)` (Snapcraft's package-information table).
+ */
 function renderHtmlTable(headRows, bodyRows, ctx, caption = "") {
     const cell = (e, tag) => {
-        const span = e.attribs?.morecols ? ` colspan="${parseInt(e.attribs.morecols, 10) + 1}"` : "";
-        const rspan = e.attribs?.morerows ? ` rowspan="${parseInt(e.attribs.morerows, 10) + 1}"` : "";
-        const inner = renderBlocks(elementChildren(e), ctx).join(" ").trim();
-        return `<${tag}${span}${rspan}>${inner}</${tag}>`;
+        const props = {};
+        if (e.attribs?.morecols)
+            props.colspan = parseInt(e.attribs.morecols, 10) + 1;
+        if (e.attribs?.morerows)
+            props.rowspan = parseInt(e.attribs.morerows, 10) + 1;
+        const md = renderBlocks(elementChildren(e), ctx).join("\n\n").trim();
+        return { type: tag, props, children: md ? dogsbayMdToTree(md).tree : [] };
     };
-    const row = (r, tag) => `<tr>${entriesOf(r).map((e) => cell(e, tag)).join("")}</tr>`;
-    const parts = ["<table>"];
-    if (caption)
-        parts.push(`<caption>${caption}</caption>`);
+    const row = (r, tag) => ({ type: "tr", children: entriesOf(r).map((e) => cell(e, tag)) });
+    const children = [];
     if (headRows.length)
-        parts.push("<thead>", ...headRows.map((r) => row(r, "th")), "</thead>");
-    parts.push("<tbody>", ...bodyRows.map((r) => row(r, "td")), "</tbody>", "</table>");
-    return parts.join("");
+        children.push({ type: "thead", children: headRows.map((r) => row(r, "th")) });
+    children.push({ type: "tbody", children: bodyRows.map((r) => row(r, "td")) });
+    const table = {
+        type: "table",
+        children,
+        // No header rows declared: the first row is data, as Sphinx renders it.
+        meta: headRows.length ? undefined : { headerless: true },
+        props: caption ? { caption } : undefined,
+    };
+    return treeToDogsbayMd([table]).trim();
 }
 // ── Inline level ─────────────────────────────────────────────────────────────
 function renderInline(nodes, ctx) {
@@ -489,26 +1003,49 @@ function renderInline(nodes, ctx) {
     }
     return out;
 }
+/** `*text*` with the text's leading and trailing whitespace OUTSIDE the
+ *  markers: `* 100 ms*` is not emphasis in CommonMark, so the asterisks
+ *  showed (a sphinx-needs need-part title starts with a space). */
+function wrapMarker(marker, text) {
+    const m = /^(\s*)([\s\S]*?)(\s*)$/.exec(text);
+    return m[2] ? `${m[1]}${marker}${m[2]}${marker}${m[3]}` : text;
+}
 function renderInlineEl(el, ctx) {
     const tag = el.tagName;
     const inner = () => renderInline(kids(el), ctx);
     switch (tag) {
         case "emphasis":
         case "title_reference":
-            return `*${inner()}*`;
+            return wrapMarker("*", inlineOneLine(inner()));
         case "strong":
-            return `**${inner()}**`;
+            return wrapMarker("**", inlineOneLine(inner()));
+        case "line":
+            // A `line` nested inside inline content (sphinx-needs' meta row: status
+            // and tags as lines within one line). A hard break inside a line block,
+            // a space anywhere else: `\` there split a table row, ended a heading
+            // or escaped a closing `**`.
+            return `${inner().trim()}${LINE_BREAK}`;
         case "literal":
             return `\`${textContent(el)}\``;
         case "reference": {
             const raw = el.attribs?.refuri ?? (el.attribs?.refid ? `#${el.attribs.refid}` : "");
-            const uri = resolveRef(raw, el.attribs?.internal === "1", ctx);
+            // A link into Sphinx's own output folder (`../_images/plantuml-….svg`,
+            // a diagram the HTML builder would have rendered) has no file here.
+            if (/(^|\/)_images\/(?:plantuml|graphviz|mermaid|inheritance)-[0-9a-f]+\.(?:svg|png)(?:#.*)?$/i.test(raw) && !/^[a-z][a-z0-9+.-]*:/i.test(raw))
+                return inner();
+            // sphinx-needs writes its cross-page need links with `refdocname` (the
+            // target's absolute docname) and no `internal`: resolved from that.
+            const docname = el.attribs?.refdocname;
+            const uri = docname && el.attribs?.refuri && !/^[a-z][a-z0-9+.-]*:/i.test(el.attribs.refuri)
+                ? resolveRef(`/${docname}${raw.includes("#") ? raw.slice(raw.indexOf("#")) : ""}`, true, ctx)
+                : resolveRef(raw, isTrue(el.attribs?.internal), ctx);
             const text = inner() || uri;
-            return uri ? `[${text}](${uri})` : text;
+            return uri ? `[${text}](${mdDest(uri)})` : text;
         }
         case "target":
             return "";
         case "footnote_reference":
+        case "citation_reference":
             return `[^${el.attribs?.refid ?? textContent(el)}]`;
         case "substitution_reference":
             return inner();
@@ -524,6 +1061,11 @@ function renderInlineEl(el, ctx) {
         case "inline":
             // The "Added in version X:" prefix span of a versionmodified note —
             // italicise it so the inline version note still reads as a note.
+            if ((el.attribs?.classes ?? "").split(/\s+/).includes("need-part") && el.attribs?.ids) {
+                // A sphinx-needs need part (`REQ_1.a`): links target its id.
+                const anchors = el.attribs.ids.split(/\s+/).filter(Boolean).map((id) => anchorTag(ctx, id)).join("");
+                return anchors + inner();
+            }
             if ((el.attribs?.classes ?? "").includes("versionmodified")) {
                 const t = inner().trim();
                 return t ? `*${t}* ` : "";
@@ -532,7 +1074,11 @@ function renderInlineEl(el, ctx) {
         case "generated":
             return inner();
         case "image":
-            return renderImage(el);
+            return renderImage(el, ctx);
+        case "raw":
+            // Inline HTML in MyST (`<spellexception>master</spellexception>`,
+            // `<kbd>`): the tags go, the words stay.
+            return (el.attribs?.format ?? "").split(/\s+/).includes("html") ? escapeText(rawHtmlText(el)) : "";
         default:
             return inner();
     }
@@ -564,10 +1110,10 @@ function descendant(el, tag) {
     return undefined;
 }
 function rowsOf(el) {
-    return elementChildren(el).filter((c) => c.tagName === "row");
+    return elementChildren(el).filter((c) => c.tagName === "row" || c.tagName === "NeedtableRow");
 }
 function entriesOf(row) {
-    return elementChildren(row).filter((c) => c.tagName === "entry");
+    return elementChildren(row).filter((c) => c.tagName === "entry" || c.tagName === "NeedtableHeader");
 }
 function cellsText(row, ctx) {
     return entriesOf(row).map((e) => {
@@ -611,7 +1157,7 @@ function resolveRef(raw, internal, ctx) {
     if (!raw)
         return "";
     if (raw[0] === "#")
-        return raw; // in-page anchor
+        return anchorFor(ctx.docPath, raw.slice(1), ctx); // in-page anchor
     if (/^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("//"))
         return raw; // URL
     if (!internal)
@@ -619,9 +1165,9 @@ function resolveRef(raw, internal, ctx) {
     // Strip a trailing .html Sphinx sometimes emits, split off #fragment.
     const hashIdx = raw.indexOf("#");
     let path = (hashIdx === -1 ? raw : raw.slice(0, hashIdx)).replace(/\.html$/i, "");
-    const frag = hashIdx === -1 ? "" : raw.slice(hashIdx);
+    const fragId = hashIdx === -1 ? "" : raw.slice(hashIdx + 1);
     if (!path)
-        return frag; // same-page ref
+        return fragId ? anchorFor(ctx.docPath, fragId, ctx) : ""; // same-page ref
     // Absolute docname (leading '/') is already root-relative.
     const segs = path.startsWith("/") ? [] : ctx.docDir ? ctx.docDir.split("/") : [];
     for (const part of path.replace(/^\//, "").split("/")) {
@@ -634,7 +1180,15 @@ function resolveRef(raw, internal, ctx) {
     }
     // Prefix with the site basePath so in-body links match the nav's hrefs.
     const prefix = ctx.hrefPrefix.replace(/\/$/, "");
-    return `${prefix}/${segs.join("/")}${frag}`;
+    const target = segs.join("/");
+    // The served path, as the other importers write it: `how-to/index` is
+    // served at `/how-to`, and `/how-to/index` is a 404 on the built site.
+    const served = target === "index" ? "" : target.replace(/\/index$/, "");
+    return `${prefix}/${served}${fragId ? anchorFor(target, fragId, ctx) : ""}`;
+}
+/** `#id`, rewritten to the heading id when the id names a section. */
+function anchorFor(doc, id, ctx) {
+    return `#${ctx.anchorOf(doc, id) ?? id}`;
 }
 // ── Escaping / fences ────────────────────────────────────────────────────────
 function escapeText(s) {
@@ -648,7 +1202,56 @@ function escapeText(s) {
     // table pipe. (`<` escaping is safe — markdown renders `\<` as a literal
     // `<`.) Leaving these unescaped let plain rST prose like `see <http://x>`
     // or `item [1]` be reinterpreted as HTML / link syntax (review #10).
-    return s.replace(/\s+/g, " ").replace(/([\\`*_[\]<|])/g, "\\$1");
+    // Braces too: `{#id}` / `{.class}` at the end of a line is attribute
+    // syntax, and `{{ }}` / `{% %}` / `{# #}` are template syntax the site
+    // build evaluates. In rST they are text. The `%`/`#` after a brace is
+    // escaped as well, since the template scanner looks for `{%` even after
+    // a backslash.
+    return s
+        .replace(/\s+/g, " ")
+        .replace(/([\\`*_[\]<|{}])/g, "\\$1")
+        .replace(/\\\{([%#])/g, "\\{\\$1");
+}
+/**
+ * The words of a raw HTML fragment: comments, `<script>`/`<style>` content
+ * and tags removed (a block-level tag leaves a space, so cells and
+ * paragraphs do not run together), entities decoded. Only something shaped
+ * like a tag is removed: `1 < 2` keeps its words.
+ */
+function rawHtmlText(el) {
+    return textContent(el)
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<(script|style)\b[\s\S]*?<\/\1\s*>/gi, " ")
+        .replace(/<\/?(?:p|div|br|td|th|tr|li|ul|ol|table|thead|tbody|h[1-6]|section|blockquote|pre|hr)\b[^>]*>/gi, " ")
+        .replace(/<\/?[a-zA-Z][^<>]*>/g, "")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * A code fence's `title="…"` value. A backtick in a fence's info string
+ * makes CommonMark reject the fence, so the code becomes paragraph text and
+ * any HTML in it live (a prompt `:user: a`b` did exactly that); quotes would
+ * end the attribute. Both are replaced, and the value is one line.
+ */
+function fenceTitle(s) {
+    return s.replace(/`/g, "'").replace(/"/g, "'").replace(/[\r\n]+/g, " ").trim();
+}
+/** Text of an element for an attribute value: no markup, no escapes, one
+ *  line, and no `"` (the parser does not decode `&quot;`). */
+function plainText(el) {
+    return textContent(el).replace(/\s+/g, " ").replace(/"/g, "'").trim();
+}
+/** A line that would start a list, heading, quote or definition is escaped,
+ *  for text placed alone on a line (a tab label). */
+function escapeLineStart(s) {
+    return s
+        .replace(/^(\d+)([.)])(?=\s|$)/, "$1\\$2")
+        // Every leading colon: `\:::note` still read `::note` as a directive.
+        .replace(/^(:+)/, (m) => m.replace(/:/g, "\\:"))
+        .replace(/^([-+#>])/, "\\$1");
 }
 function escapeAttr(s) {
     return s.replace(/"/g, "&quot;");
@@ -666,10 +1269,16 @@ function colonDepth(text) {
     }
     return max;
 }
+/**
+ * A backtick fence longer than ANY backtick run in the code (serialize-core's
+ * rule). Counting only runs at column 0 missed a closer indented 1-3 spaces,
+ * which CommonMark accepts: code holding "  ```" ended the block early and
+ * the rest of it became live HTML.
+ */
 function pickCodeFence(code) {
     let longest = 0;
-    for (const m of code.matchAll(/^(`{3,})/gm))
-        longest = Math.max(longest, m[1].length);
+    for (const m of code.matchAll(/`+/g))
+        longest = Math.max(longest, m[0].length);
     return "`".repeat(Math.max(3, longest + 1));
 }
 //# sourceMappingURL=transform.js.map