@dogsbay/format-obsidian 0.2.0-beta.15 → 0.2.0-beta.150

package/dist/serialize.js

@@ -1,3 +1,4 @@
+import { walkInline, applyTextFlags, renderLeaf, prefixLines, pickCodeFence, stripHtml, inlineHtmlToMarkdown, escapeMarkdownText, isSafeHref, codeSpan, markdownDestination, markdownTitle, markdownLatex, footnoteLabel, mapOutsideCodeSpans, neutralizeMarkdown, renderAroundGroup, } from "@dogsbay/serialize-core";
 /**
  * Transform an href for Obsidian vault paths.
  *
@@ -7,13 +8,68 @@
  *   https://example.com                 → https://example.com (unchanged)
  *   #local-anchor                       → #local-anchor (unchanged)
  */
+/**
+ * `/_assets/x.png` → `_assets/x.png`.
+ *
+ * Importers rewrite media refs to the `/_assets/…` mount convention, which is
+ * right for a served site and wrong in a vault: Obsidian resolves a link
+ * against the vault, so a leading slash finds nothing — even though the
+ * exporter copied the file to `_assets/x.png`. External and data URIs are
+ * left alone.
+ */
+/**
+ * Make asset references inside RAW HTML resolvable from the vault.
+ *
+ * A served site roots them (`/_assets/images/x.png`); a vault has no site
+ * root, so the same path resolves nowhere. `vaultAssetPath` already handles
+ * this for `image` inline nodes, but a complex AsciiDoc table is emitted as
+ * raw HTML and its cells carry their own `<img src>` — which never reaches
+ * that renderer. Five images in an OpenShift vault were dead for exactly this
+ * reason while the identical file resolved fine one paragraph earlier.
+ */
+function vaultifyHtmlAssets(html) {
+    if (!html.includes("/_assets/"))
+        return html;
+    return html
+        .replace(/(\ssrc=")\/+(_assets\/)/g, "$1$2")
+        .replace(/(\shref=")\/+(_assets\/)/g, "$1$2");
+}
+function vaultAssetPath(src) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(src))
+        return src;
+    return src.replace(/^\/+/, "");
+}
+/**
+ * Sanitize a slug into a valid Obsidian BLOCK IDENTIFIER.
+ *
+ * Obsidian block ids accept only letters, numbers and dashes. Anything else
+ * means the `^id` is not parsed as a block id at all — it renders as literal
+ * text in BOTH edit and reading view, and any `#^id` link pointing at it is
+ * dead.
+ *
+ * This is not a corner case: AsciiDoc ids join a module and its context with
+ * an underscore (`additional-resources_welcome-index`), so a real OpenShift
+ * vault had 21,509 unusable anchors across 82% of its notes, and 2,333 of its
+ * cross-references (21%) resolved to nothing. The visible tell is that a
+ * dash-only id like `^welcome-index` superscripts and hides correctly while
+ * its underscore sibling does not.
+ *
+ * MUST be applied to the anchor and to every link that targets it, or the two
+ * stop agreeing — which is worse than leaving both broken.
+ */
+export function obsidianBlockId(slug) {
+    return slug
+        .replace(/[^A-Za-z0-9-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 function obsidianHref(href) {
     // External URLs — leave as-is
     if (href.startsWith("http://") || href.startsWith("https://"))
         return href;
     // Local anchors — rewrite to block ID reference
     if (href.startsWith("#"))
-        return `#^${href.slice(1)}`;
+        return `#^${obsidianBlockId(href.slice(1))}`;
     // Strip leading /
     let result = href.replace(/^\//, "");
     // Strip trailing /
@@ -21,13 +77,43 @@ function obsidianHref(href) {
     // Normalize /#anchor to #anchor (strip / before #)
     result = result.replace(/\/#/, "#");
     // Rewrite #slug anchors to #^slug block ID references
-    result = result.replace(/#(.+)$/, "#^$1");
+    result = result.replace(/#(.+)$/, (_m, frag) => `#^${obsidianBlockId(frag)}`);
     return result;
 }
+/**
+ * Block ids already emitted for the CURRENT page.
+ *
+ * Reset per page in `treeToObsidian` (project.ts calls it exactly once per
+ * page). Obsidian indexes a block id per note, so two headings sharing one id
+ * make every `#^id` link resolve to whichever comes first — silently.
+ *
+ * Measured on OpenShift 4.22: 1,855 duplicate ids were ALREADY present in the
+ * AsciiDoc source, and sanitizing added only 2 more. So this mostly cleans up
+ * a pre-existing source problem rather than one we introduced. Links keep
+ * targeting the un-suffixed id and therefore still land on the first heading —
+ * the same behaviour as before, but without Obsidian seeing a duplicate.
+ */
+const usedBlockIds = new Set();
+function uniqueBlockId(id) {
+    if (!id)
+        return id;
+    if (!usedBlockIds.has(id)) {
+        usedBlockIds.add(id);
+        return id;
+    }
+    for (let n = 1;; n++) {
+        const candidate = `${id}-${n}`;
+        if (!usedBlockIds.has(candidate)) {
+            usedBlockIds.add(candidate);
+            return candidate;
+        }
+    }
+}
 /**
  * Convert TreeNode[] to Obsidian-flavored Markdown.
  */
 export function treeToObsidian(nodes) {
+    usedBlockIds.clear();
     return nodes.map(nodeToObsidian).filter(Boolean).join("\n\n");
 }
 // ── Block dispatcher ────────────────────────────────────
@@ -40,7 +126,7 @@ function nodeToObsidian(node) {
         case "heading":
             return headingToObsidian(node);
         case "paragraph":
-            return childrenToObsidian(node);
+            return leafContent(node);
         case "prose":
             return proseToObsidian(node);
         case "callout":
@@ -48,7 +134,7 @@ function nodeToObsidian(node) {
         case "details":
             return detailsToObsidian(node);
         case "tabs":
-            return tabsToObsidian(node);
+            return renderAroundGroup(node, "tab", tabsToObsidian, nodeToObsidian, "\n\n");
         case "code":
             return codeToObsidian(node);
         case "diagram":
@@ -68,9 +154,9 @@ function nodeToObsidian(node) {
         case "deflist":
             return deflistToObsidian(node);
         case "dt":
-            return `**${childrenToObsidian(node)}**`;
+            return `**${leafContent(node)}**`;
         case "dd":
-            return `: ${childrenToObsidian(node)}`;
+            return `: ${leafContent(node)}`;
         case "steps":
             return stepsToObsidian(node);
         case "step":
@@ -80,20 +166,39 @@ function nodeToObsidian(node) {
         case "annotation-list":
             return childrenToObsidian(node);
         case "link-button": {
-            const href = obsidianHref(node.props?.href ?? "");
-            const text = childrenToObsidian(node) || href;
-            return `[${text}](${href})`;
+            const raw = node.props?.href ?? "";
+            const href = raw && isSafeHref(raw) ? obsidianHref(raw) : "";
+            const text = childrenToObsidian(node) || esc(href);
+            return href ? `[${text}](${markdownDestination(href)})` : text;
         }
         case "hr":
             return "---";
         case "html":
-            return node.html ?? "";
+            return vaultifyHtmlAssets(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 vaultifyHtmlAssets(node.html);
             return childrenToObsidian(node);
+        case "link-card": {
+            // The parser folds a one-paragraph body into `props.description`, so a
+            // link card often has no children; with no case it emitted nothing
+            const description = node.props?.description?.trim();
+            const body = node.children?.length
+                ? node.children
+                : description ? [{ type: "paragraph", inline: [{ type: "text", text: description }] }] : [];
+            return cardToObsidian({ ...node, type: "card", children: body });
+        }
+        case "accordion":
+            return (node.children ?? []).map(nodeToObsidian).filter(Boolean).join("\n\n");
+        case "accordion-item":
+            // Each item is a collapsed fold titled with its label
+            return detailsToObsidian({ ...node, props: { title: node.props?.label ?? node.props?.title, open: node.props?.open } });
         case "figure": {
             const caption = node.props?.caption;
             const inner = childrenToObsidian(node);
-            return caption ? `${inner}\n\n*${caption}*` : inner;
+            return caption ? `${inner}\n\n*${esc(oneLine(caption))}*` : inner;
         }
         case "card":
             return cardToObsidian(node);
@@ -111,81 +216,192 @@ function nodeToObsidian(node) {
             return apiParamsToObsidian(node);
         case "api-source":
             return apiSourceToObsidian(node);
+        case "endpoint":
+            return endpointToObsidian(node);
         case "footnote-list":
             return footnoteListToObsidian(node);
         case "footnote-def":
             return footnoteDefToObsidian(node);
+        case "related": {
+            // "Additional resources" blocks — the parser models the labeled
+            // link-list as a `related` node carrying its TITLE in props. The
+            // default fallthrough emitted only the children, so every such
+            // label vanished from the vault (issue #064: first-of-two blocks,
+            // the 8 per-section labels on oadp-api, nodes-nodes-jobs' heading —
+            // links floated with no context). A missing serializer case is a
+            // silent loss.
+            const title = (node.props?.title ?? "").trim();
+            const body = childrenToObsidian(node);
+            // No invented default label (format-astro omits it too — and an
+            // English fallback is wrong for localized corpora); escape emphasis
+            // chars so a title containing `*` can't break the bold wrapper.
+            if (!title)
+                return body;
+            return `**${esc(oneLine(title))}**\n\n${body}`;
+        }
         default:
             if (node.html)
-                return stripHtml(node.html);
+                return htmlToObsidian(node.html);
             if (node.children)
                 return childrenToObsidian(node);
             return "";
     }
 }
 // ── Inline rendering ────────────────────────────────────
+/**
+ * Obsidian's inline syntax, as emitters over serialize-core's shared walk.
+ *
+ * The traversal, the nesting recursion, and the bold/italic/strike flag order
+ * used to live here as a fourth copy of the same 11-variant switch. Only the
+ * leaf syntax below is Obsidian-specific; everything structural is now shared,
+ * so a variant added to `InlineNode` surfaces in one place instead of four.
+ *
+ * Emitters are exhaustive on purpose: an omission routes through the core's
+ * `onUnsupported` plain-text degradation, which is the right default for a new
+ * variant but the WRONG behaviour for one Obsidian genuinely supports.
+ */
+const OBSIDIAN_INLINE = {
+    text: (node) => 
+    // Escape tag-like `<` in prose: markdown-it decoded the engine's
+    // `&lt;` entities into bare `<`, and Obsidian's reading view swallows
+    // `<cluster-name>` as an unknown HTML tag — the placeholder text
+    // silently disappears for the reader (issue #046). A backslash escape
+    // renders as the literal character.
+    // Every other Markdown marker too (`*x*`, `[x](…)`): text is literal.
+    applyTextFlags(esc(node.text), node, {
+        bold: (s) => `**${s}**`,
+        italic: (s) => `*${s}*`,
+        strike: (s) => `~~${s}~~`,
+    }),
+    link: (node, ctx) => {
+        if (!isSafeHref(node.href)) {
+            ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
+            return ctx.recurse(node.children);
+        }
+        return `[${ctx.recurse(node.children)}](${markdownDestination(obsidianHref(node.href))}${markdownTitle(node.title)})`;
+    },
+    // A leading slash is not a vault path — see vaultAssetPath.
+    image: (node, ctx) => {
+        if (!isSafeHref(node.src, "image")) {
+            ctx.report("image", `unsafe image source dropped (${node.src.slice(0, 40)})`);
+            return esc(node.alt ?? "");
+        }
+        return `![${(node.alt ?? "").replace(/[[\]\\]/g, "\\$&")}](${markdownDestination(vaultAssetPath(node.src))})`;
+    },
+    code: (node) => codeSpan(node.text),
+    highlight: (node, ctx) => `==${ctx.recurse(node.children)}==`,
+    "footnote-ref": (node) => `[^${footnoteLabel(node.label)}]`,
+    kbd: (node) => node.keys.map((k) => `<kbd>${escapeHtmlChars(k)}</kbd>`).join("+"),
+    math: (node) => `$${markdownLatex(node.latex)}$`,
+    icon: (node) => `:${node.name.replace(/[^\w+-]/g, "")}:`,
+    "html-inline": (node) => node._composedRun
+        ? (node.html ?? "")
+        : vaultifyHtmlAssets(node.html ?? ""),
+    break: () => "  \n",
+};
 function inlineToObsidian(nodes) {
-    return nodes.map(inlineNodeToObsidian).join("");
+    // `escape`: inline nodes without their own emitter fall back to plain text.
+    return walkInline(groupFormatRuns(nodes), { emitters: OBSIDIAN_INLINE, escape: esc });
 }
-function inlineNodeToObsidian(node) {
-    switch (node.type) {
-        case "text": {
-            let text = node.text;
-            if (node.bold && node.italic)
-                text = `***${text}***`;
-            else if (node.bold)
-                text = `**${text}**`;
-            else if (node.italic)
-                text = `*${text}*`;
-            if (node.strikethrough)
-                text = `~~${text}~~`;
-            return text;
+/**
+ * Wrap CONSECUTIVE nodes sharing the same bold/italic/strike flags in one
+ * mark pair instead of per-node wrapping. The parser inherits strong/em
+ * flags onto code spans (`**`code` text**`, issue #045); per-node
+ * emission produced `` `code`** text** `` — the code span unbolded and
+ * `** text**` (space inside the opener) not even parsing as bold. Runs
+ * are emitted as a single html-inline-free group: flags stripped from the
+ * clones, marks around the whole run, run-edge spaces shifted OUTSIDE the
+ * marks (CommonMark flanking).
+ */
+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;
         }
-        case "link": {
-            const text = inlineToObsidian(node.children);
-            const title = node.title ? ` "${node.title}"` : "";
-            return `[${text}](${obsidianHref(node.href)}${title})`;
+        let j = i;
+        while (j < nodes.length && flaggable(nodes[j]) && flagsOf(nodes[j]) === key)
+            j++;
+        // A single flagged TEXT node keeps the proven per-node path (its
+        // escaping and flag order are pinned by the byte-parity suite); the
+        // synthetic group exists only for the broken shapes — a flagged code
+        // span, or a run split across several nodes.
+        if (j === i + 1 && nodes[i].type === "text") {
+            out.push(nodes[i]);
+            i = j;
+            continue;
         }
-        case "image": {
-            const alt = node.alt ?? "";
-            return `![${alt}](${node.src})`;
+        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: OBSIDIAN_INLINE, escape: esc });
+        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;
+            }
+            // _composedRun: this is already-serialized MARKDOWN riding the
+            // html-inline pass-through, not raw HTML — the emitter must not run
+            // vaultifyHtmlAssets over it (it would rewrite `src="/_assets/…"`
+            // even inside a code span within the run).
+            out.push({ type: "html-inline", html: lead + open + inner + close + tail, _composedRun: true });
         }
-        case "code":
-            return `\`${node.text}\``;
-        case "highlight":
-            return `==${inlineToObsidian(node.children)}==`;
-        case "footnote-ref":
-            return `[^${node.label}]`;
-        case "kbd":
-            return node.keys.map((k) => `<kbd>${k}</kbd>`).join("+");
-        case "math":
-            return `$${node.latex}$`;
-        case "icon":
-            return `:${node.name}:`;
-        case "html-inline":
-            return node.html;
-        case "break":
-            return "  \n";
-        default:
-            return "";
+        else if (lead) {
+            // Whitespace-only run: lead and tail both matched the WHOLE string,
+            // so pushing lead+tail doubled the spaces. lead alone IS the run.
+            out.push({ type: "text", text: lead });
+        }
+        i = j;
     }
+    return out;
 }
 // ── Prose (inline or HTML fallback) ─────────────────────
 function proseToObsidian(node) {
     if (node.inline)
         return inlineToObsidian(node.inline);
     if (node.html)
-        return stripHtml(node.html);
+        return htmlToObsidian(node.html);
     return "";
 }
 // ── Callouts (lossless mapping) ─────────────────────────
 function calloutToObsidian(node) {
-    const variant = node.props?.variant ?? "note";
+    // Shape-tolerant: the dogsbay-md parser emits `props.type` for `:::tip`
+    // directives; importers emit `props.variant`. Reading only `variant`
+    // demoted EVERY parsed callout to note — 2,194 of the OpenShift vault's
+    // 7,926 admonitions (all its tips/warnings/importants) mislabeled.
+    const variant = (node.props?.variant ?? node.props?.type) ?? "note";
     const title = node.props?.title;
     let opener = `> [!${variant}]`;
     const autoTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
+    // The title is inline Markdown on the callout's first line.
     if (title && title !== autoTitle)
-        opener += ` ${title}`;
+        opener += ` ${esc(oneLine(title))}`;
     if (title === null)
         opener += "";
     const inner = childrenToObsidian(node);
@@ -194,14 +410,16 @@ function calloutToObsidian(node) {
     return `${opener}\n${prefixLines(inner, "> ")}`;
 }
 function detailsToObsidian(node) {
-    const variant = node.props?.variant ?? "note";
-    const title = node.props?.title;
+    // Shape-tolerant variant read — see calloutToObsidian.
+    const variant = (node.props?.variant ?? node.props?.type) ?? "note";
+    // `summary` is dogsbay-md's alias for the title (`:::details{summary="…"}`)
+    const title = (node.props?.title ?? node.props?.summary);
     const open = node.props?.open;
     const foldMarker = open ? "+" : "-";
     let opener = `> [!${variant}]${foldMarker}`;
     const autoTitle = variant.charAt(0).toUpperCase() + variant.slice(1);
     if (title && title !== autoTitle)
-        opener += ` ${title}`;
+        opener += ` ${esc(oneLine(title))}`;
     const inner = childrenToObsidian(node);
     if (!inner)
         return opener;
@@ -236,8 +454,16 @@ function tabsToObsidian(node) {
     codeBlockNestingDepth++;
     const inner = node.children
         .map((tab) => {
-        const title = tab.props?.title ?? "Tab";
+        // The parser labels a tab with `label`; older/other shapes use `title` or
+        // `value`. Mirror format-astro's tolerant cascade — reading only `title`
+        // (the old obsidian behaviour) makes every tab render as the literal "Tab".
+        let title = tab.props?.title ||
+            tab.props?.label ||
+            tab.props?.value ||
+            "Tab";
         const content = tabContentToObsidian(tab);
+        // One line: the plugin reads the header line by line.
+        title = oneLine(title);
         if (!content)
             return `tab: ${title}\n---`;
         return `tab: ${title}\n---\n${content}`;
@@ -252,8 +478,12 @@ function tabContentToObsidian(node) {
 }
 // ── Code blocks ─────────────────────────────────────────
 function codeToObsidian(node) {
-    const lang = node.props?.lang ?? "";
-    const code = (node.props?.code ?? "").replace(/\n$/, "");
+    // The parser emits `props.language` with the code text in `node.html`;
+    // importers use `props.lang`/`props.code`. Read BOTH (as format-astro does)
+    // — reading only `lang`/`code` produced an EMPTY, language-less fence for
+    // every code block parsed from real dogsbay-md.
+    const lang = node.props?.lang || node.props?.language || "";
+    const code = (node.props?.code ?? node.html ?? "").replace(/\n$/, "");
     const title = node.props?.title;
     const highlights = node.props?.highlights;
     const annotations = node.props?.annotations;
@@ -292,7 +522,7 @@ function diagramToObsidian(node) {
 // ── Math ────────────────────────────────────────────────
 function mathBlockToObsidian(node) {
     const latex = node.props?.latex ?? "";
-    return `$$\n${latex}\n$$`;
+    return `$$\n${markdownLatex(latex)}\n$$`;
 }
 // ── Tables (GFM pipe tables) ────────────────────────────
 function tableToObsidian(node) {
@@ -366,11 +596,17 @@ function orderedListToObsidian(node) {
         .map((child, i) => {
         const num = start + i;
         const text = nodeToObsidian(child);
-        const first = `${num}. ${text.split("\n")[0]}`;
+        // Continuation indent must reach the item's CONTENT column, which is
+        // the marker's own width: `10. ` is 4 wide, `100. ` is 5. A fixed
+        // 3-space indent detached every table/callout attached to item 10+
+        // (CommonMark: one column short of the content column ends the item).
+        const marker = `${num}. `;
+        const pad = " ".repeat(marker.length);
+        const first = `${marker}${text.split("\n")[0]}`;
         const rest = text.split("\n").slice(1);
         if (rest.length === 0)
             return first;
-        return `${first}\n${rest.map((l) => (l ? `   ${l}` : l)).join("\n")}`;
+        return `${first}\n${rest.map((l) => (l ? `${pad}${l}` : l)).join("\n")}`;
     })
         .join("\n");
 }
@@ -389,18 +625,77 @@ function unorderedListToObsidian(node) {
         .join("\n");
 }
 function listItemToObsidian(node) {
-    if (!node.children)
-        return "";
-    const parts = node.children.map(nodeToObsidian).filter(Boolean);
-    // Join with blank line between items to ensure Obsidian treats
-    // consecutive blockquote-style elements (callouts, details) as separate
-    return parts.join("\n\n");
+    // A list item's text is in `inline` (flat parser shape); nested blocks are
+    // in `children`. Reading only children returned "" for every plain bullet.
+    const parts = [];
+    if (node.inline && node.inline.length > 0)
+        parts.push(inlineToObsidian(node.inline));
+    if (node.children)
+        parts.push(...node.children.map(nodeToObsidian).filter(Boolean));
+    // Blank line between blocks so Obsidian treats consecutive blockquote-style
+    // elements (callouts, details) as separate.
+    return parts.filter(Boolean).join("\n\n");
 }
 // ── Definition lists (degraded) ─────────────────────────
+/**
+ * Definition list → a `dogsbay-deflist` fence the vault plugin renders as a
+ * real `<dl>`.
+ *
+ * Obsidian has NO definition-list syntax. The previous emission used the
+ * common `**term**` / `: definition` convention, which Obsidian renders as
+ * literal text with a stray colon — 821 of 2,106 notes (28,946 lines) in a
+ * real OpenShift vault. And because the `dd` case flattened its body with
+ * `leafContent`, a definition carrying a TABLE was emitted as `: ` followed by
+ * pipe rows at column 0, so the table could not parse either.
+ *
+ * Definition bodies are serialized as full BLOCK markdown, so a table, list or
+ * code block inside a `dd` survives; the plugin renders each body through
+ * Obsidian's own markdown renderer.
+ */
 function deflistToObsidian(node) {
-    if (!node.children)
+    if (!node.children?.length)
         return "";
-    return node.children.map(nodeToObsidian).join("\n");
+    const entries = [];
+    let current = null;
+    // A definition body may itself contain a fenced code block, so the wrapper
+    // alternates fence characters by nesting depth (same rule as steps/tabs).
+    const fence = codeBlockNestingDepth % 2 === 0 ? "~~~" : "```";
+    codeBlockNestingDepth++;
+    for (const child of node.children) {
+        if (child.type === "dt") {
+            if (current)
+                entries.push(current);
+            current = { term: leafContent(child).trim(), definitions: [] };
+            continue;
+        }
+        if (child.type === "dd") {
+            // Block children first — `leafContent` is the fallback for the flat
+            // `inline` shape the dogsbay-md parser produces.
+            const body = (childrenToObsidian(child) || leafContent(child)).trim();
+            if (!current)
+                current = { term: "", definitions: [] };
+            if (body)
+                current.definitions.push(body);
+            continue;
+        }
+        // Anything else inside a deflist keeps its content rather than vanishing.
+        const other = nodeToObsidian(child).trim();
+        if (!other)
+            continue;
+        if (!current)
+            current = { term: "", definitions: [] };
+        current.definitions.push(other);
+    }
+    if (current)
+        entries.push(current);
+    codeBlockNestingDepth--;
+    const body = entries
+        .map((e) => {
+        const defs = e.definitions.join("\n\n---\n").trim();
+        return defs ? `term: ${e.term}\n---\n${defs}` : `term: ${e.term}\n---`;
+    })
+        .join("\n\n");
+    return `${fence}dogsbay-deflist\n${body}\n${fence}`;
 }
 // ── Steps (numbered list) ───────────────────────────────
 function stepsToObsidian(node) {
@@ -411,7 +706,14 @@ function stepsToObsidian(node) {
     // Use dogsbay-steps element for richer rendering
     const inner = node.children
         .map((child) => {
-        const title = child.props?.title || "";
+        // A `step` node carries its TITLE as its own inline content (the parser's
+        // ordered-list recovery), with the body in `children` — the same shape
+        // format-astro renders via leafContent. Reading `props.title` (the old
+        // behaviour) dropped every step title. `props.title` remains a fallback
+        // for shapes that carry it there.
+        const title = (child.inline && child.inline.length ? inlineToObsidian(child.inline) : "") ||
+            child.props?.title ||
+            "";
         const content = childrenToObsidian(child);
         if (title) {
             return content ? `step: ${title}\n---\n${content}` : `step: ${title}\n---`;
@@ -428,7 +730,8 @@ function headingToObsidian(node) {
     const level = node.props?.level ?? 1;
     const slug = node.props?.slug ?? "";
     const hashes = "#".repeat(level);
-    const blockId = slug ? ` ^${slug}` : "";
+    const id = uniqueBlockId(obsidianBlockId(slug));
+    const blockId = id ? ` ^${id}` : "";
     if (node.inline)
         return `${hashes} ${inlineToObsidian(node.inline)}${blockId}`;
     const text = childrenToObsidian(node) || (node.props?.text ?? "");
@@ -450,22 +753,66 @@ function referencesToObsidian(node) {
         .join("\n");
 }
 function youtubeToObsidian(node) {
-    const id = node.props?.videoId ?? "";
-    const title = node.props?.title ?? "Video";
+    // The parser emits `props.id`; importers may use `props.videoId`. Read BOTH
+    // (as format-astro reads `props.id`) — reading only `videoId` produced a
+    // broken embed URL (`.../vi//maxres...`, `watch?v=`) for every parsed video.
+    const id = String(node.props?.id || node.props?.videoId || "").replace(/[^\w-]/g, "");
+    const title = (node.props?.title ?? "Video").replace(/[[\]\\\r\n]/g, " ");
     return `[![${title}](https://img.youtube.com/vi/${id}/maxresdefault.jpg)](https://www.youtube.com/watch?v=${id})`;
 }
+/**
+ * The icon value if a vault can show it, otherwise undefined.
+ *
+ * Renderable: an image path (the plugin builds an <img>), or an emoji — any
+ * non-ASCII glyph, which the plugin prints as text and which reads correctly.
+ * Not renderable: an ASCII slug naming an icon in a registry the vault does
+ * not have.
+ */
+function renderableVaultIcon(icon) {
+    if (/\.(svg|png|jpe?g|webp|avif)$/i.test(icon))
+        return vaultAssetPath(icon);
+    // eslint-disable-next-line no-control-regex
+    return /^[\x00-\x7F]+$/.test(icon) ? undefined : icon;
+}
+/** Give an internal card target the `.md` its exact-path lookup needs. */
+function cardHref(href) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("#"))
+        return href;
+    return /\.[a-z0-9]+$/i.test(href) ? href : `${href}.md`;
+}
 function cardToObsidian(node) {
-    const title = node.props?.title || "";
-    const href = node.props?.href;
+    const title = oneLine(node.props?.title || "");
+    const rawHref = node.props?.href;
+    const href = rawHref && isSafeHref(rawHref) ? oneLine(rawHref) : undefined;
     const icon = node.props?.icon;
     const content = childrenToObsidian(node);
     const header = [];
     if (title)
         header.push(`title: ${title}`);
+    // `.md` REQUIRED here, unlike an ordinary markdown link.
+    //
+    // A `[text](path)` link is resolved by Obsidian's own linkpath lookup, which
+    // is forgiving about the extension. This href is consumed by the dogsbay-docs
+    // plugin, which resolves it with `vault.getFileByPath()` — an EXACT match.
+    // Extensionless, that returns null and the click does nothing at all: the
+    // cards rendered correctly and were simply inert, with no error anywhere.
     if (href)
-        header.push(`href: ${obsidianHref(href)}`);
-    if (icon)
-        header.push(`icon: ${icon}`);
+        header.push(`href: ${cardHref(obsidianHref(href))}`);
+    // Only an icon the VAULT can render.
+    //
+    // The plugin draws an image when the icon is a file path and prints the
+    // value as text otherwise — which is right for an emoji and wrong for a
+    // registry NAME. Starlight names like `open-book`, `discord` and `x.com`
+    // have no file behind them and no registry in a vault, so they rendered as
+    // the literal word "discord" stacked one letter per line down the card's
+    // icon column.
+    //
+    // A name we cannot resolve is dropped rather than emitted: the card simply
+    // has no icon, which is what it would look like anyway if the reference
+    // worked and pointed at nothing.
+    const vaultIcon = icon ? renderableVaultIcon(icon) : undefined;
+    if (vaultIcon)
+        header.push(`icon: ${vaultIcon}`);
     if (header.length === 0 && !content)
         return "";
     const meta = header.join("\n");
@@ -487,13 +834,20 @@ function apiSymbolToObsidian(node) {
     const level = node.type === "api-class" ? 3 : 4;
     const hashes = "#".repeat(level);
     const sig = node.props?.signature ?? "";
-    const bases = node.props?.bases;
+    // The parser emits `bases` as a string; the RST/autodoc importer (and
+    // format-astro's read) may use a string[]. Tolerate both.
+    const basesRaw = node.props?.bases;
+    const bases = Array.isArray(basesRaw)
+        ? basesRaw.join(", ")
+        : basesRaw;
     const parts = [];
-    parts.push(`${hashes} ${kind} \`${name}\``);
+    parts.push(`${hashes} ${esc(kind)} ${codeSpan(name)}`);
     if (bases)
-        parts.push(`Bases: \`${bases}\``);
-    if (sig)
-        parts.push(`\`\`\`python\n${sig}\n\`\`\``);
+        parts.push(`Bases: ${codeSpan(bases)}`);
+    if (sig) {
+        const fence = chooseFence(sig);
+        parts.push(`${fence}python\n${sig}\n${fence}`);
+    }
     if (node.children)
         parts.push(childrenToObsidian(node));
     return parts.filter(Boolean).join("\n\n");
@@ -542,7 +896,7 @@ function apiDocToObsidian(node) {
     // api-doc has HTML content in props.html — convert to markdown
     const html = node.props?.html ?? "";
     if (html)
-        return stripHtml(html);
+        return htmlToObsidian(html);
     return childrenToObsidian(node);
 }
 function apiSourceToObsidian(node) {
@@ -557,6 +911,166 @@ function apiSourceToObsidian(node) {
     if (code) {
         parts.push(`\`\`\`python\n${code.replace(/\n$/, "")}\n\`\`\``);
     }
+    else if (node.children && node.children.length > 0) {
+        // The dogsbay-md parser puts the fenced source into a child `code` node
+        // (props.language + node.html), not props.code — reading only props.code
+        // dropped the source block. Serialize children as a fallback; the
+        // props.code path stays for importers that carry it there.
+        const inner = childrenToObsidian(node);
+        if (inner)
+            parts.push(inner);
+    }
+    return parts.join("\n\n");
+}
+const objects = (v) => (Array.isArray(v) ? v.filter((x) => !!x && typeof x === "object") : []);
+const text = (v) => (v == null ? "" : String(v));
+/** A GFM table cell: one line, pipes escaped (GFM unescapes them inside code spans too). */
+function cell(md) {
+    return oneLine(md).replace(/\|/g, "\\|");
+}
+/** A spec description (CommonMark, from someone else's file) in a table cell, inert. */
+function descriptionCell(p) {
+    const parts = [neutralizeMarkdown(oneLine(text(p.description)))];
+    if (Array.isArray(p.enum) && p.enum.length)
+        parts.push(`One of: ${p.enum.map((v) => codeSpan(text(v))).join(", ")}`);
+    if (p.default !== undefined)
+        parts.push(`Default: ${codeSpan(typeof p.default === "string" ? p.default : JSON.stringify(p.default))}`);
+    if (p.example !== undefined)
+        parts.push(`Example: ${codeSpan(JSON.stringify(p.example))}`);
+    if (p.deprecated === true)
+        parts.push("*Deprecated.*");
+    return cell(parts.filter(Boolean).join(" "));
+}
+function typeCell(p) {
+    const t = text(p.type) || "any";
+    return cell(codeSpan(p.format ? `${t} <${text(p.format)}>` : t) + (p.nullable === true ? " (nullable)" : ""));
+}
+function table(head, rows) {
+    return [`| ${head.join(" | ")} |`, `|${head.map(() => " --- ").join("|")}|`, ...rows.map((r) => `| ${r.join(" | ")} |`)].join("\n");
+}
+/** Schema properties, nested ones flattened to `owner.id` / `tags[].name`, as the rows of one table. */
+function propertyRows(props, prefix = "", depth = 0) {
+    if (depth > 10)
+        return [];
+    return props.flatMap((p) => {
+        const name = `${prefix}${text(p.name)}`;
+        const row = [cell(codeSpan(name)), typeCell(p), p.required === true ? "yes" : "", descriptionCell(p)];
+        const nested = objects(p.properties).length
+            ? propertyRows(objects(p.properties), `${name}.`, depth + 1)
+            : propertyRows(objects(p.items), `${name}[].`, depth + 1);
+        return [row, ...nested];
+    });
+}
+/** A foldable callout holding a code block (samples and examples). */
+function codeCallout(title, code, lang) {
+    const fence = chooseFence(code);
+    // The language is the spec's: a backtick or newline in it would keep the fence from opening, and the code would render as Markdown.
+    const info = /^[\w#+.-]{1,40}$/.test(lang) ? lang : "";
+    return `> [!example]- ${esc(oneLine(title))}\n${prefixLines(`${fence}${info}\n${code.replace(/\n$/, "")}\n${fence}`, "> ")}`;
+}
+/**
+ * A spec description, inert; its own headings as bold lines (they would sit
+ * in the note's outline under the operation, as on the web, where they are
+ * bold paragraphs); and any fence it opens closed: an unclosed one would turn
+ * the rest of the note into code.
+ */
+function specMarkdown(md) {
+    let open;
+    const lines = neutralizeMarkdown(md).split("\n").map((line) => {
+        const m = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (m) {
+            if (!open)
+                open = m[1];
+            else if (m[1][0] === open[0] && m[1].length >= open.length && line.trim() === m[1])
+                open = undefined;
+            return line;
+        }
+        const h = open ? null : /^ {0,3}#{1,6}(?:[ \t]+(.*?))?(?:[ \t]+#+)?[ \t]*$/.exec(line);
+        return h ? (h[1] ? `**${h[1]}**` : "") : line;
+    });
+    // Setext headings (a text line underlined with === or ---): the text bold, the underline gone.
+    for (let k = 1, fence = false; k < lines.length; k++) {
+        if (/^ {0,3}(`{3,}|~{3,})/.test(lines[k - 1]))
+            fence = !fence;
+        const prev = lines[k - 1];
+        if (fence || !/^ {0,3}(=+|-+)[ \t]*$/.test(lines[k]))
+            continue;
+        if (!prev.trim() || /^ {0,3}([-*+>]|\d+[.)]|#|\*\*.*\*\*$)/.test(prev))
+            continue;
+        lines[k - 1] = `**${prev.trim()}**`;
+        lines[k] = "";
+    }
+    const out = lines.join("\n");
+    return open ? `${out}\n${open}` : out;
+}
+/** ExampleBlock's language for a response content type. */
+function exampleLang(contentType) {
+    const base = contentType.split(";")[0].trim();
+    if (!base || base.includes("json"))
+        return "json";
+    if (base.includes("xml"))
+        return "xml";
+    if (base.includes("yaml") || base.includes("yml"))
+        return "yaml";
+    if (base === "text/html")
+        return "html";
+    return /^text\/plain$|form/.test(base) ? "" : "json";
+}
+const SAMPLE_LABELS = {
+    curl: "cURL", python: "Python", typescript: "TypeScript", javascript: "JavaScript", go: "Go",
+    ruby: "Ruby", java: "Java", csharp: "C#", php: "PHP", rust: "Rust",
+};
+/**
+ * An OpenAPI operation (`endpoint`, from format-openapi or the MDX adapters)
+ * as vault Markdown: the method and path as a heading, the description,
+ * tables for parameters, the request body and responses, and the code
+ * samples and examples as folded callouts. Every description is the spec
+ * author's Markdown, made inert (neutralizeMarkdown) as format-astro renders
+ * it with raw HTML off. With no case here the default emitted the node's
+ * (absent) children: every operation vanished from a vault without a word.
+ */
+function endpointToObsidian(node) {
+    const p = (node.props ?? {});
+    const method = (text(p.method) || "get").toUpperCase();
+    const path = text(p.path);
+    const parts = [`### ${codeSpan(method)} ${codeSpan(path)}`];
+    if (p.summary)
+        parts.push(esc(oneLine(text(p.summary))));
+    if (p.deprecated === true)
+        parts.push("> [!warning] Deprecated\n> This endpoint is deprecated.");
+    if (typeof p.description === "string" && p.description.trim() && p.description !== p.summary) {
+        parts.push(specMarkdown(p.description.trim()));
+    }
+    if (p.baseUrl)
+        parts.push(`URL: ${codeSpan(text(p.baseUrl) + path)}`);
+    const params = objects(p.parameters);
+    if (params.length) {
+        parts.push("**Parameters**", table(["Name", "In", "Type", "Required", "Description"], params.map((x) => [cell(codeSpan(text(x.name))), cell(esc(text(x.in))), typeCell(x), x.required === true ? "yes" : "", descriptionCell(x)])));
+    }
+    const body = objects(p.requestBody);
+    if (body.length)
+        parts.push("**Request body**", table(["Property", "Type", "Required", "Description"], propertyRows(body)));
+    const responses = objects(p.responses);
+    if (responses.length) {
+        parts.push("**Responses**", table(["Status", "Description"], responses.map((r) => [cell(codeSpan(text(r.status))), cell(neutralizeMarkdown(oneLine(text(r.description))))])));
+        for (const r of responses) {
+            const schema = objects(r.schema);
+            if (!schema.length)
+                continue;
+            parts.push(`> [!info]- ${esc(`Response ${text(r.status)} schema`)}\n${prefixLines(table(["Property", "Type", "Required", "Description"], propertyRows(schema)), "> ")}`);
+        }
+    }
+    for (const s of objects(p.codeSamples)) {
+        const lang = text(s.language);
+        parts.push(codeCallout(text(s.label) || SAMPLE_LABELS[lang] || lang, text(s.code), lang === "curl" ? "bash" : lang));
+    }
+    if (p.requestBodyExample !== undefined)
+        parts.push(codeCallout("Request body example", JSON.stringify(p.requestBodyExample, null, 2), "json"));
+    for (const r of responses) {
+        if (r.example === undefined)
+            continue;
+        parts.push(codeCallout(`Response ${text(r.status)} example`, JSON.stringify(r.example, null, 2), exampleLang(text(r.contentType))));
+    }
     return parts.join("\n\n");
 }
 // ── Footnotes ───────────────────────────────────────────
@@ -566,8 +1080,13 @@ function footnoteListToObsidian(node) {
     return node.children.map(nodeToObsidian).join("\n");
 }
 function footnoteDefToObsidian(node) {
-    const label = node.props?.label ?? "1";
-    const content = childrenToObsidian(node);
+    const label = footnoteLabel(String(node.props?.label ?? "1"));
+    // The dogsbay-md parser puts the definition body on `inline` (flat
+    // shape); reading only `children` dropped every footnote body — the
+    // three-TreeNode-shapes lesson documented at leafContent below.
+    const content = node.inline && node.inline.length > 0
+        ? inlineToObsidian(node.inline)
+        : childrenToObsidian(node);
     return `[^${label}]: ${content}`;
 }
 // ── Utilities ───────────────────────────────────────────
@@ -576,50 +1095,65 @@ function childrenToObsidian(node) {
         return "";
     return node.children.map(nodeToObsidian).filter(Boolean).join("\n\n");
 }
-function prefixLines(text, prefix) {
-    return text
-        .split("\n")
-        .map((line) => (line ? `${prefix}${line}` : prefix.trimEnd()))
-        .join("\n");
-}
-function indent(text, spaces) {
-    const prefix = " ".repeat(spaces);
-    return text
-        .split("\n")
-        .map((line) => (line ? `${prefix}${line}` : line))
-        .join("\n");
-}
 /**
- * Choose a fence string (```) that doesn't conflict with content.
- * Scans for the longest run of backticks in the content and uses one more.
+ * Text-bearing content across all THREE TreeNode shapes.
+ *
+ * Was a local re-derivation handling only two of them (flat `inline` and
+ * `children`). It now goes through the core's `renderLeaf`, which adds the
+ * third — a node carrying only `html`, or a single wrapped `prose` child
+ * carrying `html` with no `inline` (what the MDX/Starlight/MkDocs importers
+ * emit). Reading only the first two rendered those nodes EMPTY; that is the
+ * bug that shipped in the Docusaurus exporter's first version and dropped
+ * every paragraph body on a real Mintlify conversion.
+ *
+ * The `join` is "\n\n" to preserve this serializer's paragraph spacing (the
+ * core defaults to "\n").
  */
-function chooseFence(content) {
-    let max = 2;
-    const matches = content.match(/`{3,}/g);
-    if (matches) {
-        for (const m of matches) {
-            if (m.length > max)
-                max = m.length;
-        }
-    }
-    return "`".repeat(max + 1);
+function leafContent(node) {
+    return renderLeaf(node, {
+        inline: inlineToObsidian,
+        children: (children) => children.map(nodeToObsidian).filter(Boolean).join("\n\n"),
+        html: htmlToObsidian,
+        join: "\n\n",
+    });
 }
 /**
- * Strip HTML tags, preserving text content.
- * Handles common inline HTML from prose nodes.
+ * Render pre-rendered prose HTML as Obsidian markdown.
+ *
+ * `stripHtml` alone DELETES tags, so every `<code>`, `<strong>`, `<em>` and
+ * `<a>` an importer hands us became plain text. That is invisible for sources
+ * whose prose nodes also carry `inline` (mkdocs), and catastrophic for those
+ * that carry ONLY html — the MDX/Mintlify shape. Measured on a full Mintlify
+ * export before this fix: 38,994 inline code spans in the source became 6,864
+ * in the vault, and 14,548 bold runs became 3,465. Roughly 80% of inline
+ * formatting, silently gone, on the export we point at as the back-out.
+ *
+ * `inlineHtmlToMarkdown` converts the unambiguous inline tags to real markdown
+ * first; `stripHtml` then removes whatever markup is left and decodes entities.
  */
-function stripHtml(html) {
-    return html
-        .replace(/<br\s*\/?>/gi, "\n")
-        .replace(/<\/p>\s*<p[^>]*>/gi, "\n\n")
-        .replace(/<\/?(?:p|div|span|strong|em|s|a|code|sup|sub|mark|kbd|abbr)[^>]*>/gi, "")
-        .replace(/<img[^>]+alt="([^"]*)"[^>]*>/gi, "![$1]")
-        .replace(/<[^>]+>/g, "")
-        .replace(/&amp;/g, "&")
-        .replace(/&lt;/g, "<")
-        .replace(/&gt;/g, ">")
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
-        .trim();
-}
-//# sourceMappingURL=serialize.js.map
+function htmlToObsidian(html) {
+    // Applied HERE because this is the shared path for prose, html-container and
+    // inline HTML. Raw `<img src="/_assets/…">` most often arrives inline inside
+    // a paragraph, not as a standalone `html` node — 39 vault images stayed
+    // site-rooted when only the block case was covered.
+    // BEFORE the html→markdown conversion: `inlineHtmlToMarkdown` turns
+    // `<img src>` into `![alt](src)`, after which there is no `src=` attribute
+    // left to rewrite.
+    // stripHtml decodes entities: an `&lt;img onerror=…&gt;` that was TEXT
+    // came back tag-shaped, and Obsidian renders inline HTML.
+    // Code spans are left as written: a backslash there would show.
+    return mapOutsideCodeSpans(stripHtml(inlineHtmlToMarkdown(vaultifyHtmlAssets(html), { flatten: true })), (t) => t.replace(/<(?=[A-Za-z/!?])/g, "\\<"));
+}
+/** Literal text as vault Markdown (`\<`, which reads better than `&lt;`
+ *  in a file people edit). */
+function esc(text) {
+    return escapeMarkdownText(text, { style: "backslash" });
+}
+/** Text for a one-line header or label: newlines folded to spaces. */
+function oneLine(s) {
+    return s.replace(/\s*[\r\n]+\s*/g, " ");
+}
+/** Obsidian's code fence, via the core's shared longest-run picker. */
+function chooseFence(content) {
+    return pickCodeFence(content);
+}