@dogsbay/format-obsidian 0.2.0-beta.1 → 0.2.0-beta.101

package/dist/serialize.js

@@ -1,3 +1,4 @@
+import { walkInline, applyTextFlags, renderLeaf, prefixLines, pickCodeFence, stripHtml, inlineHtmlToMarkdown, } 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":
@@ -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":
@@ -87,7 +173,7 @@ function nodeToObsidian(node) {
         case "hr":
             return "---";
         case "html":
-            return node.html ?? "";
+            return vaultifyHtmlAssets(node.html ?? "");
         case "html-container":
             return childrenToObsidian(node);
         case "figure": {
@@ -115,72 +201,169 @@ function nodeToObsidian(node) {
             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 `**${title.replace(/([*\\])/g, "\\$1")}**\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.
+    applyTextFlags(node.text.replace(/<(?=[A-Za-z/])/g, "\\<"), node, {
+        bold: (s) => `**${s}**`,
+        italic: (s) => `*${s}*`,
+        strike: (s) => `~~${s}~~`,
+    }),
+    link: (node, ctx) => {
+        const title = node.title ? ` "${node.title}"` : "";
+        return `[${ctx.recurse(node.children)}](${obsidianHref(node.href)}${title})`;
+    },
+    // A leading slash is not a vault path — see vaultAssetPath.
+    image: (node) => `![${node.alt ?? ""}](${vaultAssetPath(node.src)})`,
+    code: (node) => `\`${node.text}\``,
+    highlight: (node, ctx) => `==${ctx.recurse(node.children)}==`,
+    "footnote-ref": (node) => `[^${node.label}]`,
+    kbd: (node) => node.keys.map((k) => `<kbd>${k}</kbd>`).join("+"),
+    math: (node) => `$${node.latex}$`,
+    icon: (node) => `:${node.name}:`,
+    "html-inline": (node) => node._composedRun
+        ? (node.html ?? "")
+        : vaultifyHtmlAssets(node.html ?? ""),
+    break: () => "  \n",
+};
 function inlineToObsidian(nodes) {
-    return nodes.map(inlineNodeToObsidian).join("");
+    return walkInline(groupFormatRuns(nodes), { emitters: OBSIDIAN_INLINE });
 }
-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 });
+        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);
@@ -194,7 +377,8 @@ function calloutToObsidian(node) {
     return `${opener}\n${prefixLines(inner, "> ")}`;
 }
 function detailsToObsidian(node) {
-    const variant = node.props?.variant ?? "note";
+    // Shape-tolerant variant read — see calloutToObsidian.
+    const variant = (node.props?.variant ?? node.props?.type) ?? "note";
     const title = node.props?.title;
     const open = node.props?.open;
     const foldMarker = open ? "+" : "-";
@@ -236,7 +420,13 @@ 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".
+        const title = tab.props?.title ||
+            tab.props?.label ||
+            tab.props?.value ||
+            "Tab";
         const content = tabContentToObsidian(tab);
         if (!content)
             return `tab: ${title}\n---`;
@@ -252,8 +442,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;
@@ -366,11 +560,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 +589,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 +670,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 +694,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,10 +717,33 @@ function referencesToObsidian(node) {
         .join("\n");
 }
 function youtubeToObsidian(node) {
-    const id = node.props?.videoId ?? "";
+    // 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 = node.props?.id || node.props?.videoId || "";
     const title = node.props?.title ?? "Video";
     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;
@@ -462,10 +752,30 @@ function cardToObsidian(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,7 +797,12 @@ 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}\``);
     if (bases)
@@ -542,7 +857,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 +872,15 @@ 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");
 }
 // ── Footnotes ───────────────────────────────────────────
@@ -567,7 +891,12 @@ function footnoteListToObsidian(node) {
 }
 function footnoteDefToObsidian(node) {
     const label = node.props?.label ?? "1";
-    const content = childrenToObsidian(node);
+    // 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 +905,54 @@ 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();
+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.
+    return stripHtml(inlineHtmlToMarkdown(vaultifyHtmlAssets(html)));
+}
+/** Obsidian's code fence, via the core's shared longest-run picker. */
+function chooseFence(content) {
+    return pickCodeFence(content);
 }
 //# sourceMappingURL=serialize.js.map