@dogsbay/format-vitepress 0.2.0-beta.101

package/dist/translate.js

@@ -0,0 +1,882 @@
+/**
+ * VitePress Markdown → Dogsbay-MD text.
+ *
+ * VitePress markdown is CommonMark + `:::` containers + a handful of
+ * code-fence conventions + Vue. It is a near-superset of Dogsbay-MD, so this
+ * is a delimiter rewrite rather than a parser: once containers are renamed and
+ * fence metadata is normalized, `dogsbayMdToTree` defines correctness and we
+ * introduce zero new TreeNode types. Same pipeline as `format-gitbook` and
+ * `format-myst`.
+ *
+ * Everything this translator cannot map is recorded in a ledger. A migration
+ * that loses a construct silently is worse than one that says so.
+ */
+// ── Container vocabulary ──────────────────────────────────────────────────
+/** VitePress container name → Dogsbay-MD directive name. */
+const CALLOUTS = {
+    info: "info",
+    note: "note",
+    tip: "tip",
+    warning: "warning",
+    danger: "danger",
+    // VitePress inherited `caution` from its markdown-it-container defaults in
+    // some themes; Dogsbay has no `caution`, and warning is the nearest.
+    caution: "warning",
+};
+/** Containers whose body passes through with the wrapper removed. */
+const TRANSPARENT = new Set(["raw", "v-pre", "html"]);
+// ── Public entry point ────────────────────────────────────────────────────
+export function vitepressToDogsbayMd(source, opts = {}) {
+    const ledger = [];
+    const components = {};
+    const ctx = { ledger, components, opts, depth: 0 };
+    return translateWith(source, ctx);
+}
+function translateWith(source, ctx) {
+    const { ledger, components } = ctx;
+    let text = source.replace(/\r\n?/g, "\n");
+    text = stripVueBlocks(text, ctx);
+    const lines = text.split("\n");
+    const nodes = parseRange(lines, { start: 0, end: lines.length }, ctx);
+    const rendered = renderNodes(nodes);
+    return { markdown: rendered.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n", ledger, components };
+}
+/**
+ * Containers may be INDENTED — VitePress's own deployment guide nests a
+ * `::: code-group` three spaces deep inside a numbered list, and
+ * markdown-it-container accepts up to three spaces of indentation. Anchoring
+ * these at column 0 left every such container as literal `::: code-group`
+ * text in the page, with its tabs unbuilt.
+ *
+ * The indent is CAPTURED and re-emitted on the translated directive, so the
+ * container stays inside the list item it belongs to instead of being hoisted
+ * out of it.
+ */
+const OPEN_RE = /^( {0,3})(:{3,})\s*([A-Za-z][\w-]*)\s*(.*)$/;
+const CLOSE_RE = /^ {0,3}(:{3,})\s*$/;
+const FENCE_RE = /^(\s*)(`{3,}|~{3,})(.*)$/;
+/**
+ * Walk a line range, tracking fenced code blocks, and call `onLine` for every
+ * line that is NOT inside a fence. Returns nothing; used by the closer scan
+ * and the tab splitter so both agree with the main loop about what is code.
+ */
+function scanOutsideFences(lines, range, onLine) {
+    let i = range.start;
+    while (i < range.end) {
+        const fence = lines[i].match(FENCE_RE);
+        if (fence) {
+            const marker = fence[2];
+            const closeRe = new RegExp(`^\\s*${marker[0]}{${marker.length},}\\s*$`);
+            i++;
+            while (i < range.end && !closeRe.test(lines[i]))
+                i++;
+            i++;
+            continue;
+        }
+        if (onLine(lines[i], i) === true)
+            return;
+        i++;
+    }
+}
+/**
+ * Find the line that closes a container opened with `markerLen` colons.
+ *
+ * This is markdown-it-container's ACTUAL rule, and getting it wrong is the
+ * difference between a readable page and a page swallowed whole:
+ *
+ *   - a closer is a line of AT LEAST `markerLen` colons and nothing else;
+ *   - the scan runs from the opener to the end of the ENCLOSING range;
+ *   - a container with no closer in that range auto-closes at the range end.
+ *
+ * Crucially the extent is fixed when the container OPENS, before its children
+ * are parsed. The earlier implementation recursed innermost-first, so an
+ * unclosed inner container consumed the closer meant for its parent and every
+ * outer container then ran to end of file. vitest's browser-mode page opens
+ * four containers (`warning` > `tabs` > `code-group` > `code-group`) and
+ * provides ONE `:::` for all of them — under the old rule that one closer went
+ * to the innermost code-group and the `warning` callout swallowed the rest of
+ * the document.
+ */
+function findCloser(lines, range, markerLen) {
+    const closeRe = new RegExp(`^ {0,3}:{${markerLen},}\\s*$`);
+    let found = range.end;
+    scanOutsideFences(lines, range, (line, index) => {
+        if (closeRe.test(line)) {
+            found = index;
+            return true;
+        }
+    });
+    return found;
+}
+/**
+ * Split a `::: tabs` body on its `== Label` markers BEFORE any container in it
+ * is parsed.
+ *
+ * `vitepress-plugin-tabs` divides the raw body first, so an unclosed
+ * `::: code-group` inside one tab cannot leak into the next one. Parsing
+ * containers first instead merged every fence between the two markers into a
+ * single tab strip — the live vitest page shows Playwright and WebdriverIO
+ * with four package-manager tabs each; we produced one provider tab with
+ * fifteen, several of them duplicate labels (which `<Tabs>` cannot even
+ * address, since it matches by string equality).
+ */
+function splitTabRanges(lines, range) {
+    const marks = [];
+    scanOutsideFences(lines, range, (line, index) => {
+        const m = line.match(/^\s*==\s+(.*)$/);
+        if (m)
+            marks.push({ title: m[1].trim(), at: index });
+    });
+    const pre = { start: range.start, end: marks.length ? marks[0].at : range.end };
+    const sections = marks.map((mark, i) => ({
+        title: mark.title,
+        range: { start: mark.at + 1, end: i + 1 < marks.length ? marks[i + 1].at : range.end },
+    }));
+    return { pre, sections };
+}
+/**
+ * Parse a line range into a region tree.
+ *
+ * Fence-aware: a `:::` inside a fenced code block is literal text. VitePress's
+ * own docs contain exactly that (the page documenting containers).
+ */
+function parseRange(lines, range, ctx) {
+    const nodes = [];
+    /**
+     * Buffered lines, segmented by whether they are inside a fenced code block.
+     * Prose rewrites (component stripping, `{{ }}` neutralization, `.md` link
+     * normalization) must NOT run inside a fence: the Vue docs a VitePress site
+     * ships are full of `<Foo />` and `{{ msg }}` shown as code, and rewriting
+     * those corrupts the very examples the page exists to display.
+     */
+    let buf = [];
+    let i = range.start;
+    const flush = () => {
+        if (buf.length === 0)
+            return;
+        // Each segment reports its OWN first line. Attributing the whole coalesced
+        // run to the flush point sent every prose ledger entry to wherever the
+        // buffer happened to end — end of file on a container-free page, so a
+        // `{{ }}` on line 3 was reported at line 403.
+        const text = buf
+            .map((seg) => (seg.code ? seg.text : transformProse(seg.text, seg.line, ctx)))
+            .join("\n");
+        nodes.push({ kind: "text", text });
+        buf = [];
+    };
+    while (i < range.end) {
+        const line = lines[i];
+        // Fenced code block — consume whole, translating its info string.
+        const fence = line.match(FENCE_RE);
+        if (fence) {
+            const [, indent, marker, info] = fence;
+            const closeRe = new RegExp(`^\\s*${marker[0]}{${marker.length},}\\s*$`);
+            const body = [];
+            let j = i + 1;
+            while (j < range.end && !closeRe.test(lines[j])) {
+                body.push(lines[j]);
+                j++;
+            }
+            buf.push({
+                code: true,
+                line: i + 1,
+                text: [
+                    `${indent}${marker}${translateFenceInfo(info, i + 1, ctx)}`,
+                    ...body,
+                    `${indent}${marker}`,
+                ].join("\n"),
+            });
+            i = j + 1;
+            continue;
+        }
+        // A marker-only line here belongs to no open container in this range —
+        // drop it rather than emit a `:::` dogsbay-md would read as an empty
+        // directive.
+        if (CLOSE_RE.test(line)) {
+            i++;
+            continue;
+        }
+        const open = line.match(OPEN_RE);
+        if (open) {
+            flush();
+            const indent = open[1];
+            const markerLen = open[2].length;
+            const name = open[3].toLowerCase();
+            const rest = open[4].trim();
+            const body = { start: i + 1, end: range.end };
+            const closeAt = findCloser(lines, body, markerLen);
+            if (closeAt === range.end) {
+                ctx.ledger.push({
+                    construct: `::: ${name}`,
+                    note: "no closing fence before its parent ended — VitePress requires the OUTER container to use more colons than the inner",
+                    line: i + 1,
+                });
+            }
+            nodes.push(...mapContainer(name, rest, lines, { start: i + 1, end: closeAt }, i + 1, ctx, indent));
+            i = closeAt < range.end ? closeAt + 1 : range.end;
+            continue;
+        }
+        // Coalesce adjacent prose lines into ONE segment — `stripComponents`
+        // matches paired tags across lines, so per-line segmentation would miss
+        // every multi-line `<Foo>…</Foo>`.
+        const last = buf[buf.length - 1];
+        if (last && !last.code)
+            last.text += `\n${line}`;
+        else
+            buf.push({ code: false, text: line, line: i + 1 });
+        i++;
+    }
+    flush();
+    return nodes;
+}
+/**
+ * Make tab titles unique within one group.
+ *
+ * `<Tabs defaultValue>` and `<TabsTrigger value>` are matched by STRING
+ * EQUALITY, so two tabs sharing a title are not two tabs — the second is
+ * unreachable, and clicking its trigger shows the first. VitePress tolerates
+ * the duplicate (it keys by index) and vitest's own CLI page ships one: a
+ * `code-group` with two `[npm]` blocks. Suffixing keeps both reachable, and
+ * the change of label is recorded rather than made quietly.
+ */
+function uniqueTitles(raw, construct, line, ctx) {
+    const seen = new Map();
+    let changed = false;
+    const out = raw.map((title) => {
+        const n = seen.get(title) ?? 0;
+        seen.set(title, n + 1);
+        if (n === 0)
+            return title;
+        changed = true;
+        return `${title} (${n + 1})`;
+    });
+    if (changed) {
+        ctx.ledger.push({
+            construct,
+            note: "duplicate tab titles were numbered so every tab stays reachable",
+            line,
+        });
+    }
+    return out;
+}
+/** Map one VitePress container to zero or more Dogsbay-MD directives. */
+function mapContainer(name, rest, lines, body, line, ctx, indent = "") {
+    // A container's TITLE is not prose and never reaches `transformProse`, but
+    // authors put components in it — vitest writes
+    // `::: warning WARNING <Version>3.2.0</Version>`. Left alone, that tag ends
+    // up in a `title="…"` attribute and then in an .astro page, where an
+    // undefined component is a hard build error.
+    rest = sanitizeTitle(rest, ctx);
+    // `tabs` splits its RAW body on `== Label` BEFORE any nested container is
+    // parsed — see splitTabRanges. Every other container parses its body first.
+    if (name === "tabs") {
+        const { pre, sections } = splitTabRanges(lines, body);
+        if (sections.length === 0) {
+            ctx.ledger.push({ construct: "::: tabs", note: "no `==` tab markers found", line });
+            return parseRange(lines, body, ctx);
+        }
+        const titles = uniqueTitles(sections.map((sec) => sec.title), "::: tabs", line, ctx);
+        const tabs = sections.map((sec, idx) => ({
+            kind: "dir",
+            name: "tab",
+            attrs: attrBlock({ title: titles[idx] }),
+            indent,
+            children: parseRange(lines, sec.range, ctx),
+        }));
+        const out = [];
+        const lead = parseRange(lines, pre, ctx);
+        if (lead.length > 0) {
+            ctx.ledger.push({
+                construct: "::: tabs",
+                note: "content before the first tab kept as a sibling block",
+                line,
+            });
+            out.push(...lead);
+        }
+        out.push({ kind: "dir", name: "tabs", attrs: "", indent, children: tabs });
+        return out;
+    }
+    const children = parseRange(lines, body, ctx);
+    if (TRANSPARENT.has(name)) {
+        // `raw` / `v-pre` only suppress Vue compilation — no rendered wrapper.
+        return children;
+    }
+    if (name === "code-group") {
+        const { pre, sections } = codeGroupSections(children, ctx);
+        return sectionsToTabs(pre, sections, children, "::: code-group", line, ctx, indent);
+    }
+    if (name === "details") {
+        const title = rest || "Details";
+        return [{ kind: "dir", name: "details", attrs: attrBlock({ title }), indent, children }];
+    }
+    const callout = CALLOUTS[name];
+    if (callout) {
+        if (name === "caution") {
+            ctx.ledger.push({ construct: "::: caution", note: "mapped to :::warning", line });
+        }
+        return [
+            { kind: "dir", name: callout, attrs: rest ? attrBlock({ title: rest }) : "", indent, children },
+        ];
+    }
+    // An unknown container (a site's own markdown-it-container plugin). Keep the
+    // CONTENT and record the loss — an unmapped `:::name` would otherwise reach
+    // dogsbay-md, which has no container registered for it, and render as
+    // literal `:::name` text in the page.
+    ctx.ledger.push({
+        construct: `::: ${name}`,
+        note: "unknown container — wrapper dropped, content preserved",
+        line,
+    });
+    return children;
+}
+function pushText(nodes, text) {
+    if (!text.trim())
+        return;
+    nodes.push({ kind: "text", text });
+}
+/**
+ * `::: code-group` holds fenced blocks whose info string carries a `[label]`.
+ * Each fence starts a new tab; the label becomes its title.
+ */
+function codeGroupSections(children, ctx) {
+    const pre = [];
+    const sections = [];
+    const target = () => (sections.length ? sections[sections.length - 1].nodes : pre);
+    for (const child of children) {
+        if (child.kind === "dir") {
+            target().push(child);
+            continue;
+        }
+        const lines = child.text.split("\n");
+        let buf = [];
+        let i = 0;
+        while (i < lines.length) {
+            const fence = lines[i].match(FENCE_RE);
+            if (!fence) {
+                buf.push(lines[i]);
+                i++;
+                continue;
+            }
+            pushText(target(), buf.join("\n"));
+            buf = [];
+            const [, fIndent, marker, info] = fence;
+            const closeRe = new RegExp(`^\\s*${marker[0]}{${marker.length},}\\s*$`);
+            const body = [];
+            let j = i + 1;
+            while (j < lines.length && !closeRe.test(lines[j])) {
+                body.push(lines[j]);
+                j++;
+            }
+            // The info string was ALREADY translated by parseRegions, so the label
+            // now lives in `title="…"` rather than `[…]`.
+            const title = info.match(/title="([^"]*)"/)?.[1] || info.trim().split(/\s+/)[0] || "Tab";
+            sections.push({
+                title,
+                nodes: [
+                    {
+                        kind: "text",
+                        text: [`${fIndent}${marker}${info}`, ...body, `${fIndent}${marker}`].join("\n"),
+                    },
+                ],
+            });
+            i = j + 1;
+        }
+        pushText(target(), buf.join("\n"));
+    }
+    return { pre, sections };
+}
+/**
+ * Turn sections into a `:::tabs` node, with any leading content emitted as a
+ * SIBLING before it rather than dropped.
+ *
+ * VitePress itself ignores content before the first tab marker, but a
+ * migration must not delete text just because the source renderer hid it —
+ * especially since the commonest cause is an unclosed container upstream,
+ * where the "leading content" is the rest of the page.
+ */
+function sectionsToTabs(pre, sections, children, construct, line, ctx, indent) {
+    if (sections.length === 0) {
+        ctx.ledger.push({ construct, note: "no tab boundaries found — emitted as plain content", line });
+        return children;
+    }
+    const titles = uniqueTitles(sections.map((sec) => sec.title), construct, line, ctx);
+    const tabs = sections.map((sec, idx) => ({
+        kind: "dir",
+        name: "tab",
+        attrs: attrBlock({ title: titles[idx] }),
+        indent,
+        children: sec.nodes,
+    }));
+    const out = [];
+    if (pre.length > 0) {
+        ctx.ledger.push({
+            construct,
+            note: "content before the first tab kept as a sibling block",
+            line,
+        });
+        out.push(...pre);
+    }
+    out.push({ kind: "dir", name: "tabs", attrs: "", indent, children: tabs });
+    return out;
+}
+// ── Code fence info strings ───────────────────────────────────────────────
+/**
+ * VitePress fence metadata → a single trailing `{…}` attrs block, which is
+ * what `dogsbayMdToTree` reads (markdown-it-attrs attaches it to the fence
+ * token; a bare `1,3-5` key becomes `props.highlights`).
+ *
+ *   ts [vitest.config.ts]   → ts {title="vitest.config.ts"}
+ *   js{1,3-5}               → js {1,3-5}
+ *   ts:line-numbers=2       → ts {lineNumbers="2"}
+ *   ts:no-line-numbers      → ts
+ *   js twoslash [a.js]      → js {title="a.js"}
+ *
+ * The attrs block MUST be last — markdown-it-attrs only reads a trailing one.
+ */
+export function translateFenceInfo(info, line, ctx) {
+    let rest = info.trim();
+    if (!rest)
+        return "";
+    const attrs = [];
+    let highlights = "";
+    // `[title]` — anywhere in the info string, but conventionally last.
+    rest = rest.replace(/\[([^\]]*)\]/, (_m, t) => {
+        attrs.push(`title="${escapeAttr(String(t))}"`);
+        return " ";
+    });
+    // `{1,3-5}` line ranges, and `{...}` blocks generally.
+    rest = rest.replace(/\{([^}]*)\}/g, (_m, body) => {
+        const b = String(body).trim();
+        if (/^[\d,\-\s]+$/.test(b))
+            highlights = b;
+        else if (b)
+            attrs.push(b);
+        return " ";
+    });
+    const tokens = rest.split(/\s+/).filter(Boolean);
+    const kept = [];
+    for (const tok of tokens) {
+        // Language plus colon-suffixed modifiers: `ts:line-numbers=2`.
+        const [head, ...mods] = tok.split(":");
+        for (const mod of mods) {
+            if (mod === "no-line-numbers")
+                continue;
+            const m = mod.match(/^line-numbers(?:=(\d+))?$/);
+            if (m) {
+                attrs.push(m[1] ? `lineNumbers="${m[1]}"` : "lineNumbers");
+                continue;
+            }
+            if (mod) {
+                ctx?.ledger.push({
+                    construct: `\`\`\`…:${mod}`,
+                    note: "unknown fence modifier dropped",
+                    line,
+                });
+            }
+        }
+        if (!head)
+            continue;
+        // Shiki transformers that are build-time only.
+        if (head === "twoslash" || head === "vue-html-twoslash") {
+            ctx?.ledger.push({ construct: "```… twoslash", note: "Twoslash type hints dropped", line });
+            continue;
+        }
+        kept.push(head);
+    }
+    const lang = kept.shift() ?? "";
+    // Anything left over was an unrecognized bare word — keep it out of the
+    // language slot but say so.
+    for (const extra of kept) {
+        ctx?.ledger.push({ construct: `\`\`\`… ${extra}`, note: "unrecognized fence token dropped", line });
+    }
+    const attrParts = [highlights, ...attrs].filter(Boolean);
+    if (attrParts.length === 0)
+        return lang;
+    return `${lang} {${attrParts.join(" ")}}`;
+}
+// ── Prose-level rewrites ──────────────────────────────────────────────────
+/**
+ * Rewrites applied to non-fenced text. Order matters: snippets and includes
+ * are resolved first (they inject fenced code and markdown of their own),
+ * then Vue is neutralized, then links are normalized.
+ */
+function transformProse(text, line, ctx) {
+    let out = text;
+    out = resolveIncludes(out, line, ctx);
+    out = resolveSnippets(out, line, ctx);
+    out = stripToc(out, line, ctx);
+    out = rewriteBadges(out);
+    out = stripComponents(out, ctx);
+    out = neutralizeInterpolation(out, line, ctx);
+    out = rewriteMdLinks(out);
+    out = rewriteAssets(out, ctx, line);
+    return out;
+}
+/** Point image references at the exporter's asset mount. */
+function rewriteAssets(text, ctx, line) {
+    const map = ctx.opts.assetHref;
+    if (!map)
+        return text;
+    let out = text.replace(/(!\[[^\]]*\]\()([^)\s]+)/g, (_m, head, src) => `${head}${map(src)}`);
+    // `(?<![:\w-])src` so a Vue BINDING (`:src`, `v-bind:src`) is left alone.
+    // `\bsrc` matches inside `:src="` — the `:`→`s` transition is a word
+    // boundary — so every dynamic image on vitest's IDE page was rewritten into
+    // a `/_assets/pages/…` path built from an unevaluated template literal. That
+    // is worse than not rewriting: the reference now looks resolved and 404s.
+    out = out.replace(/(<img\b[^>]*?(?<![:\w-])src\s*=\s*")([^"]+)(")/g, (whole, head, src, tail) => {
+        // A template literal or interpolation cannot be resolved statically.
+        if (/[`$]\{|`/.test(src)) {
+            ctx.ledger.push({
+                construct: "<img> with a computed src",
+                note: "Vue-computed image source left as authored — it cannot be resolved without a Vue runtime",
+                line,
+            });
+            return whole;
+        }
+        return `${head}${map(src)}${tail}`;
+    });
+    // Bound sources are skipped above by design; record them separately, or the
+    // skip is itself a silent loss.
+    for (const _ of out.matchAll(/<img\b[^>]*(?::|v-bind:)src\s*=/g)) {
+        ctx.ledger.push({
+            construct: "<img> with a computed src",
+            note: "Vue-bound image source left as authored — it cannot be resolved without a Vue runtime",
+            line,
+        });
+    }
+    return out;
+}
+/** `<!--@include: ./file.md[#region]-->` — splice the referenced markdown. */
+function resolveIncludes(text, line, ctx) {
+    return text.replace(/<!--\s*@include:\s*([^\s>]+?)\s*-->/g, (whole, spec) => {
+        const { path, region } = splitRegion(String(spec));
+        const content = ctx.opts.readSnippet?.({ path, region });
+        if (content === undefined) {
+            ctx.ledger.push({
+                construct: `<!--@include: ${spec}-->`,
+                note: "include target not found — reference dropped",
+                line,
+            });
+            return "";
+        }
+        if (ctx.depth >= 4) {
+            ctx.ledger.push({
+                construct: `<!--@include: ${spec}-->`,
+                note: "include nesting exceeded 4 levels — not expanded",
+                line,
+            });
+            return "";
+        }
+        // The included file is VitePress markdown too — containers, code-group and
+        // all — so it goes through the same translation, not a verbatim splice.
+        // It is translated with options anchored at ITS OWN directory: a fragment's
+        // `./inner.md` means the fragment's sibling, not the including page's.
+        const nextDir = ctx.opts.resolveDir?.(path);
+        const nestedOpts = nextDir && ctx.opts.optionsForDir ? ctx.opts.optionsForDir(nextDir) : ctx.opts;
+        const nested = translateWith(content, {
+            ...ctx,
+            opts: nestedOpts,
+            depth: ctx.depth + 1,
+        });
+        return `\n${nested.markdown.trim()}\n`;
+    });
+}
+/** `<<< @/path[#region][{meta}]` — splice the file as a fenced code block. */
+function resolveSnippets(text, line, ctx) {
+    // The whole rest of the line is captured and then taken apart, rather than
+    // matched with one shape. Requiring `{…}` to be glued to the path and end
+    // the line meant `<<< @/f.js [title]` and `<<< @/f.js#region {1,3}` — both
+    // documented VitePress syntax — matched NOTHING: the snippet was never
+    // inlined and the raw `<<<` line was left in the page, with no ledger entry.
+    // Up to three spaces of indentation, CAPTURED and re-emitted on every line
+    // of the inlined block. Vite's own deployment guide puts a `<<<` inside a
+    // numbered list item; anchored at column 0 the reference matched nothing and
+    // the raw `<<<` line was left in the page. Emitting the fence flush left
+    // would be no better — it would break out of the list item it belongs to.
+    return text.replace(/^( {0,3})<<<\s*(.+?)\s*$/gm, (whole, indent, rest) => {
+        let spec = String(rest);
+        let title;
+        let meta = "";
+        spec = spec.replace(/\[([^\]]*)\]\s*$/, (_m, t) => {
+            title = t;
+            return "";
+        });
+        spec = spec.replace(/\{([^}]*)\}/, (_m, m2) => {
+            meta = `{${m2}}`;
+            return "";
+        });
+        spec = spec.trim();
+        if (!spec)
+            return whole;
+        const { path, region } = splitRegion(spec);
+        const content = ctx.opts.readSnippet?.({ path, region });
+        if (content === undefined) {
+            ctx.ledger.push({
+                construct: `<<< ${spec}`,
+                note: "snippet file not found — reference dropped",
+                line,
+            });
+            return "";
+        }
+        const lang = langFromPath(path);
+        const info = translateFenceInfo(`${lang}${meta} [${title ?? basename(path)}]`, line, ctx);
+        const fence = pickCodeFence(content);
+        const body = content.replace(/\n+$/, "");
+        const block = [`${fence}${info}`, ...body.split("\n"), fence];
+        return indent ? block.map((l) => (l ? `${indent}${l}` : l)).join("\n") : block.join("\n");
+    });
+}
+function stripToc(text, line, ctx) {
+    if (!text.includes("[[toc]]"))
+        return text;
+    ctx.ledger.push({
+        construct: "[[toc]]",
+        note: "inline table of contents dropped — the layout renders its own TOC",
+        line,
+    });
+    return text.replace(/^\s*\[\[toc\]\]\s*$/gm, "");
+}
+/**
+ * `<Badge type="tip" text="1.9.0" />` → a styled span.
+ *
+ * There is no `badge` TreeNode, and inventing one for a single source format
+ * is the wrong trade. A span survives every serializer (Astro passes raw HTML
+ * through; Obsidian markdown renders inline HTML) and keeps the text visible.
+ */
+function rewriteBadges(text) {
+    const span = (attrs, label) => {
+        const type = attrs.match(/\btype\s*=\s*["']([^"']*)["']/)?.[1] ?? "info";
+        const t = label.trim();
+        return t ? `<span class="vp-badge ${escapeAttr(type)}">${t}</span>` : "";
+    };
+    // The SLOT form `<Badge type="x">label</Badge>` must be handled first and as
+    // a pair. Matching the open tag alone consumed it and left an orphan
+    // `</Badge>` behind — which then reached the .astro page as a closer for an
+    // undefined component, in headings, on ten-plus real pages.
+    let out = text.replace(/<Badge\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/Badge>/g, (_m, attrs, inner) => {
+        const explicit = attrs.match(/\btext\s*=\s*["']([^"']*)["']/)?.[1];
+        return span(attrs, explicit ?? inner);
+    });
+    out = out.replace(/<Badge\b((?:[^>"']|"[^"]*"|'[^']*')*)\/?>/g, (_m, attrs) => span(attrs, attrs.match(/\btext\s*=\s*["']([^"']*)["']/)?.[1] ?? ""));
+    return out;
+}
+/** `<script setup>` / `<style>` blocks — Vue plumbing with no rendered output. */
+function stripVueBlocks(text, ctx) {
+    const lines = text.split("\n");
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        // A fence is copied through verbatim, so a `<script>` shown INSIDE a code
+        // example is never treated as Vue plumbing.
+        const fence = lines[i].match(FENCE_RE);
+        if (fence) {
+            const marker = fence[2];
+            const closeRe = new RegExp(`^\\s*${marker[0]}{${marker.length},}\\s*$`);
+            out.push(lines[i]);
+            i++;
+            while (i < lines.length && !closeRe.test(lines[i])) {
+                out.push(lines[i]);
+                i++;
+            }
+            if (i < lines.length) {
+                out.push(lines[i]);
+                i++;
+            }
+            continue;
+        }
+        const open = lines[i].match(/^<(script|style)\b/);
+        if (open) {
+            const tag = open[1];
+            const closeRe = new RegExp(`^</${tag}>\\s*$`);
+            let j = i + 1;
+            // The closer is searched for OUTSIDE fences too, and the block is only
+            // dropped if one is found — an unpaired `<script>` is left alone rather
+            // than allowed to swallow the rest of the page.
+            while (j < lines.length && !closeRe.test(lines[j]) && !FENCE_RE.test(lines[j]))
+                j++;
+            if (j < lines.length && closeRe.test(lines[j])) {
+                ctx.ledger.push({
+                    construct: `<${tag}>`,
+                    note: `Vue ${tag} block dropped`,
+                    line: i + 1,
+                });
+                i = j + 1;
+                continue;
+            }
+            ctx.ledger.push({
+                construct: `<${tag}>`,
+                note: `unclosed <${tag}> left as authored rather than dropped`,
+                line: i + 1,
+            });
+        }
+        out.push(lines[i]);
+        i++;
+    }
+    return out.join("\n");
+}
+/**
+ * Reduce a container title to plain text: a badge becomes its label, component
+ * tags are removed (and counted), and any remaining markup is dropped.
+ */
+function sanitizeTitle(title, ctx) {
+    if (!title)
+        return title;
+    let out = rewriteBadges(title);
+    out = stripComponents(out, ctx);
+    out = out.replace(/<\/?[A-Za-z][^>]*>/g, "");
+    return out.replace(/\s+/g, " ").trim();
+}
+/**
+ * Strip Vue single-file components used in markdown.
+ *
+ * These MUST go: a `<Version />` reaching an `.astro` page is an undefined
+ * component and a hard build error, not a cosmetic problem. Paired tags keep
+ * their inner content; self-closing ones vanish. Every tag is counted and
+ * named in the import summary, because a component nested inside a mapped
+ * container is not "dropped" — its tag leaks into the page as text, which is
+ * the failure mode `format-starlight` was built to surface.
+ *
+ * Only PascalCase names qualify, and a bare `<Word>` with no attributes and no
+ * closing tag is left alone — prose placeholders like `<USERNAME>` and
+ * `<Response>` are not components.
+ */
+function stripComponents(text, ctx) {
+    const count = (name) => {
+        ctx.components[name] = (ctx.components[name] ?? 0) + 1;
+    };
+    // Self-closing: `<Foo />`, `<Foo bar="baz" />`
+    let out = text.replace(
+    // Attribute values may contain `>` (`<Foo cond="a > b" />`). `[^>]*` ended
+    // the tag early, corrupting the text and leaving the component uncounted.
+    /<([A-Z][A-Za-z0-9]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)\/>/g, (_m, name) => {
+        count(name);
+        return "";
+    });
+    // Paired: `<Foo …>inner</Foo>` — keep the inner content.
+    for (let pass = 0; pass < 4; pass++) {
+        const before = out;
+        out = out.replace(/<([A-Z][A-Za-z0-9]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/\1>/g, (_m, name, _attrs, inner) => {
+            count(name);
+            return inner;
+        });
+        if (out === before)
+            break;
+    }
+    return out;
+}
+/**
+ * Vue interpolation has no runtime here, and — worse — `{{ x }}` is also minja
+ * syntax, so leaving it would let the build resolve it to nothing. Rendering
+ * it as inline code keeps the author's intent visible and inert.
+ */
+function neutralizeInterpolation(text, line, ctx) {
+    let found = false;
+    const out = text.replace(/(`+)([^`\n]*)\1|\{\{([^}\n]+)\}\}/g, (whole, tick, _code, expr) => {
+        if (tick)
+            return whole; // already inside inline code
+        found = true;
+        return `\`{{${expr}}}\``;
+    });
+    if (found) {
+        ctx.ledger.push({
+            construct: "{{ expression }}",
+            note: "Vue interpolation rendered as inline code (no Vue runtime in the target)",
+            line,
+        });
+    }
+    return out;
+}
+/**
+ * `[x](./guide/foo.md)` → `[x](./guide/foo)`. VitePress serves extensionless
+ * URLs, so the `.md` in a link is a source-tree detail, not part of the href.
+ * External URLs and non-markdown targets are untouched.
+ */
+function rewriteMdLinks(text) {
+    return text.replace(/\]\(([^)\s]+?)\.md(#[^)\s]*)?\)/g, (whole, target, hash) => {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target))
+            return whole; // absolute URL
+        return `](${target}${hash ?? ""})`;
+    });
+}
+// ── Rendering ─────────────────────────────────────────────────────────────
+/**
+ * markdown-it-container closes an outer `:::` at the first bare `:::`, so a
+ * directive must use MORE colons than anything nested inside it — including a
+ * TEXT child that already carries a `:::` (a resolved include can).
+ */
+function longestColonFence(text) {
+    let max = 0;
+    for (const l of text.split("\n")) {
+        const m = l.match(/^ {0,3}(:{3,})/);
+        if (m)
+            max = Math.max(max, m[1].length);
+    }
+    return max;
+}
+function fenceLen(node) {
+    let innerMax = 0;
+    for (const c of node.children) {
+        innerMax = Math.max(innerMax, c.kind === "dir" ? fenceLen(c) : longestColonFence(c.text));
+    }
+    return Math.max(3, innerMax + 1);
+}
+/** Strip leading/trailing blank lines while leaving indentation intact. */
+function trimBlankLines(text) {
+    return text.replace(/^(?:[ \t]*\n)+/, "").replace(/(?:\n[ \t]*)+$/, "");
+}
+function renderNodes(nodes) {
+    const parts = [];
+    for (const n of nodes) {
+        if (n.kind === "text") {
+            parts.push(n.text);
+        }
+        else {
+            const colons = ":".repeat(fenceLen(n));
+            // Trim blank lines, NOT indentation: an indented container's first
+            // inner line carries the list indentation that keeps it in its item.
+            const inner = trimBlankLines(renderNodes(n.children));
+            parts.push(`${n.indent}${colons}${n.name}${n.attrs}\n${inner}\n${n.indent}${colons}`);
+        }
+    }
+    return parts.join("\n");
+}
+// ── Small helpers ─────────────────────────────────────────────────────────
+function attrBlock(props) {
+    const parts = Object.entries(props)
+        .filter(([, v]) => v !== "")
+        .map(([k, v]) => `${k}="${escapeAttr(v)}"`);
+    return parts.length ? `{${parts.join(" ")}}` : "";
+}
+function escapeAttr(v) {
+    return v.replace(/"/g, "&quot;").replace(/\n+/g, " ").trim();
+}
+export function splitRegion(spec) {
+    const hash = spec.indexOf("#");
+    if (hash < 0)
+        return { path: spec };
+    return { path: spec.slice(0, hash), region: spec.slice(hash + 1) || undefined };
+}
+function basename(p) {
+    const parts = p.split("/");
+    return parts[parts.length - 1] || p;
+}
+const EXT_LANG = {
+    ts: "ts", mts: "ts", cts: "ts", tsx: "tsx",
+    js: "js", mjs: "js", cjs: "js", jsx: "jsx",
+    json: "json", jsonc: "jsonc", yml: "yaml", yaml: "yaml",
+    vue: "vue", svelte: "svelte", md: "md", html: "html", css: "css",
+    sh: "sh", bash: "bash", toml: "toml", rs: "rust", py: "python",
+    ansi: "ansi", txt: "text",
+};
+function langFromPath(p) {
+    const ext = p.split(".").pop()?.toLowerCase() ?? "";
+    return EXT_LANG[ext] ?? "";
+}
+/** A fence long enough not to collide with backticks in the content. */
+function pickCodeFence(content) {
+    let max = 2;
+    for (const m of content.matchAll(/^\s*(`{3,})/gm))
+        max = Math.max(max, m[1].length);
+    return "`".repeat(Math.max(3, max + 1));
+}
+//# sourceMappingURL=translate.js.map