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

package/dist/parse-mdx.d.ts

@@ -13,11 +13,48 @@
  * - The adapter pattern for site-specific component mappings
  */
 import type { TreeNode } from "@dogsbay/types";
-import type { SiteAdapter } from "./adapter.js";
+import type { IncludeOptions, SiteAdapter } from "./adapter.js";
+/**
+ * MDX reads the TEXT inside JSX/HTML elements as Markdown; a raw HTML block
+ * here is emitted as it is. Two Markdown forms in that text then broke the
+ * page: a code span (`` `Array<String>` `` in a `<td>` — the browser read
+ * `<String>` as a tag and the type vanished; 10 on the Cloudflare corpus) and
+ * a backslash escape (`Promise\<InstanceStatus>` inside `<code>` showed the
+ * backslash). Both become their HTML: `<code>` with escaped text, `&lt;`.
+ * Only TEXT between tags is touched — never inside a tag (attribute values)
+ * or inside `<pre>`, `<script>`, `<style>`.
+ */
+export declare function mdxHtmlText(html: string): string;
+/**
+ * MDX has no HTML blocks: every tag line is its own JSX element. Markdown's
+ * HTML block runs to the next BLANK line, so a component written straight
+ * after a `<p>…</p>` line was swallowed into it and leaked as a tag
+ * (`<AnchorHeading>`, `<Aside>` in Cloudflare's JSX branches). A blank line
+ * goes between them — only after a line that is one COMPLETE element, so an
+ * open `<table>` or `<ul>` that the component sits inside is left whole.
+ */
+export declare function endHtmlBlocksAtComponents(source: string): string;
+/**
+ * `<Feature header="…"> Paid add-on` — text after a CONTAINER's opener on
+ * its line — is the start of the body in MDX. The block rule took the line
+ * as the opener and the text was lost with no report (web3: two plan badges).
+ * It moves to its own line, at the opener's indent. A component after the
+ * opener is `normalizeJsxLines`' job; a closer on the same line is an inline
+ * use and is left alone.
+ */
+export declare function splitContainerOpenerText(source: string, isContainer: (tag: string) => boolean): string;
 export interface ParseOptions {
     adapter?: SiteAdapter;
+    /**
+     * The page's front matter, when the caller has already split it off (the
+     * CLI parses the BODY). Components that read it (`<ProductReleaseNotes>`)
+     * otherwise saw nothing.
+     */
+    frontmatter?: Record<string, unknown>;
     /** Directory containing partial MDX files for <Render> resolution */
     partialsDir?: string;
+    /** How partials are resolved (inline, or template-page directives). */
+    includeOptions?: IncludeOptions;
     /**
      * Called with the tag name of every component DROPPED from the output —
      * one that no builtin and no adapter mapping claimed.

package/dist/parse-mdx.js

@@ -12,13 +12,19 @@
  * - Card grouping (consecutive cards → cards container)
  * - The adapter pattern for site-specific component mappings
  */
+import { assignHeadingSlugs } from "./github-slug.js";
 import MarkdownIt from "markdown-it";
+import mdFootnote from "markdown-it-footnote";
 import mdxJsx, { normalizeJsxLines } from "@dogsbay/markdown-it-mdx-jsx";
 import { extractFrontmatter } from "./parse.js";
+import { outsideFences } from "./fences.js";
+import { parseJsLiteral } from "./js-literal.js";
 // ── Component mapping ───────────────────────────────────
 // Starlight built-in components (always available)
 const STARLIGHT_COMPONENTS = {
-    Tabs: { type: "tabs", container: true },
+    // `syncKey` switches every group sharing it together (db-tabs honours it);
+    // dropping it made each group independent.
+    Tabs: { type: "tabs", container: true, propsFromAttrs: (attrs) => (attrs.syncKey ? { syncKey: attrs.syncKey } : {}) },
     TabItem: {
         type: "tab",
         container: true,
@@ -72,13 +78,35 @@ const STARLIGHT_COMPONENTS = {
         type: "code",
         container: false,
         propsFromAttrs: (attrs) => ({
-            code: attrs.code || "",
+            code: codeAttr(attrs.code),
             lang: attrs.lang || "plaintext",
             title: attrs.title,
         }),
     },
 };
 const CORE_SELF_CLOSING = ["LinkCard", "Badge", "Code"];
+/**
+ * `<Code code={`…`} />`: the attribute arrives RAW, braces and backticks
+ * included, and the block showed them (`` `} `` as its last line — which also
+ * unbalanced the fences around it). A literal is read (never run) and
+ * dedented as authored; anything else (a variable) stays as written.
+ */
+function codeAttr(raw) {
+    if (!raw)
+        return "";
+    if (!raw.startsWith("{"))
+        return raw;
+    const v = parseJsLiteral(raw.slice(1, -1));
+    if (typeof v !== "string")
+        return raw;
+    const opensOnLine = !/^[ \t]*\r?\n/.test(v); // `{`const a = 1;` — its first line has no indent to count
+    const lines = v.replace(/^[ \t]*\r?\n/, "").replace(/\s+$/, "").split("\n");
+    const counted = (opensOnLine ? lines.slice(1) : lines).filter((l) => l.trim());
+    const indent = Math.min(...counted.map((l) => /^[ \t]*/.exec(l)[0].length));
+    if (!Number.isFinite(indent) || indent <= 0)
+        return lines.join("\n");
+    return lines.map((l, k) => (opensOnLine && k === 0 ? l : l.slice(Math.min(indent, /^[ \t]*/.exec(l)[0].length)))).join("\n");
+}
 function buildComponentMap(adapter) {
     const map = { ...STARLIGHT_COMPONENTS };
     const selfClosing = [...CORE_SELF_CLOSING];
@@ -98,11 +126,14 @@ function buildComponentMap(adapter) {
 function applyInlineTransforms(source, adapter) {
     if (!adapter?.inlineTransforms)
         return source;
-    let result = source;
-    for (const [regex, replacement] of adapter.inlineTransforms) {
-        result = result.replace(regex, replacement);
-    }
-    return result;
+    // Outside code: a style guide SHOWS `<Type text="string" />` in a fence,
+    // and rewriting it there changed the example into its output.
+    return outsideFences(source, (text) => {
+        let result = text;
+        for (const [regex, replacement] of adapter.inlineTransforms)
+            result = result.replace(regex, replacement);
+        return result;
+    });
 }
 /**
  * Rewrite the `~/assets/` Vite alias to the `/_assets/` mount convention.
@@ -174,6 +205,11 @@ function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
                     const props = mapping.propsFromAttrs?.(attrs) || {};
                     tree.push({ type: mapping.type, props, children: [] });
                 }
+                else if (!mapping.container && !mapping.silent) {
+                    // Stripped, and what it rendered is gone: say so. Silent strips hid
+                    // 190+ pages of lost listings from the report.
+                    onDrop?.(token.tag);
+                }
             }
             i++;
             continue;
@@ -203,20 +239,23 @@ function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
                 if (mapping.strip) {
                     // Strip but keep inner content parsed
                     if (mapping.container && children.length > 0) {
-                        const innerNodes = tokensToTree(children, componentMap);
+                        const innerNodes = tokensToTree(children, componentMap, onDrop, describeComponent);
                         tree.push(...innerNodes);
                     }
+                    else if (!mapping.container && !mapping.silent) {
+                        onDrop?.(tag);
+                    }
                 }
                 else {
                     const attrs = token.meta?.attrs || {};
                     const props = mapping.propsFromAttrs?.(attrs) || {};
-                    const childNodes = tokensToTree(children, componentMap);
+                    const childNodes = tokensToTree(children, componentMap, onDrop, describeComponent);
                     tree.push({ type: mapping.type, props, children: childNodes });
                 }
             }
             else {
                 // Unknown component — parse inner content as markdown
-                const childNodes = tokensToTree(children, componentMap);
+                const childNodes = tokensToTree(children, componentMap, onDrop, describeComponent);
                 tree.push(...childNodes);
             }
             continue;
@@ -310,7 +349,7 @@ function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
                     }
                     // Recursively parse the list item content using tokensToTree
                     // This handles nested lists, JSX components, paragraphs, etc.
-                    const itemChildren = tokensToTree(itemTokens, componentMap);
+                    const itemChildren = tokensToTree(itemTokens, componentMap, onDrop, describeComponent);
                     items.push({ type: "list-item", children: itemChildren });
                     i++; // skip list_item_close
                 }
@@ -335,17 +374,50 @@ function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
             continue;
         }
         if (token.type === "blockquote_open") {
-            const children = [];
-            i++;
-            while (i < tokens.length && tokens[i].type !== "blockquote_close") {
-                const nested = tokensToTree(tokens.slice(i, i + 1), componentMap, onDrop, describeComponent);
-                children.push(...nested);
+            // The whole body at once, to the MATCHING close. It used to be parsed
+            // one token at a time, so a paragraph never saw its inline token and
+            // every blockquote came out empty.
+            const start = ++i;
+            let depth = 1;
+            while (i < tokens.length) {
+                if (tokens[i].type === "blockquote_open")
+                    depth++;
+                if (tokens[i].type === "blockquote_close" && --depth === 0)
+                    break;
                 i++;
             }
+            const children = tokensToTree(tokens.slice(start, i), componentMap, onDrop, describeComponent);
             i++; // skip close
             tree.push({ type: "blockquote", children });
             continue;
         }
+        if (token.type === "footnote_block_open") {
+            const end = tokens.findIndex((t, k) => k > i && t.type === "footnote_block_close");
+            const close = end === -1 ? tokens.length : end;
+            const defs = [];
+            for (let k = i + 1; k < close; k++) {
+                if (tokens[k].type !== "footnote_open")
+                    continue;
+                const meta = (tokens[k].meta ?? {});
+                const label = meta.label ?? String((meta.id ?? 0) + 1);
+                let defEnd = k + 1;
+                while (defEnd < close && tokens[defEnd].type !== "footnote_close")
+                    defEnd++;
+                const body = tokens.slice(k + 1, defEnd).filter((t) => t.type !== "footnote_anchor");
+                for (const t of body)
+                    if (t.children)
+                        t.children = t.children.filter((c) => c.type !== "footnote_anchor");
+                defs.push({
+                    type: "footnote-def",
+                    props: { id: `fn-${label}`, backrefId: `fnref-${label}`, label },
+                    children: tokensToTree(body, componentMap, onDrop, describeComponent),
+                });
+                k = defEnd;
+            }
+            tree.push({ type: "footnote-list", children: defs });
+            i = close + 1;
+            continue;
+        }
         if (token.type === "html_block") {
             // Check if this is a leftover JSX component that wasn't caught
             const trimmed = token.content.trim();
@@ -369,7 +441,7 @@ function tokensToTree(tokens, componentMap, onDrop, describeComponent) {
                 i++;
                 continue;
             }
-            tree.push({ type: "html", html: token.content });
+            tree.push({ type: "html", html: mdxHtmlText(token.content) });
             i++;
             continue;
         }
@@ -430,13 +502,23 @@ function parseTable(tokens, start) {
     };
 }
 // ── Inline token conversion ─────────────────────────────
+/**
+ * The parse in progress, for inline positions (paragraphs, table cells): a
+ * stripped component there loses its content as surely as a block one, but
+ * `inlineTokensToInline` has no reporter of its own. Set for the duration of
+ * one `starlightToTree` call (parsing is synchronous).
+ */
+let inlineContext;
 function inlineTokensToInline(tokens) {
     const result = [];
     let bold = false;
     let italic = false;
     let inLink = false;
     let linkHref = "";
+    let linkTitle;
     let linkChildren = [];
+    /** The inline component that opened the current link (`<LinkButton>`), if any. */
+    let inlineButton;
     const push = (node) => {
         if (inLink)
             linkChildren.push(node);
@@ -467,14 +549,17 @@ function inlineTokensToInline(tokens) {
         }
         else if (token.type === "link_open") {
             linkHref = token.attrGet("href") || "";
+            linkTitle = token.attrGet("title") || undefined;
             linkChildren = [];
             inLink = true;
         }
         else if (token.type === "link_close") {
             if (inLink) {
+                // The Markdown title (`[x](href "Title")`) was dropped with the rest.
                 result.push({
                     type: "link",
                     href: linkHref,
+                    ...(linkTitle ? { title: linkTitle } : {}),
                     children: linkChildren,
                 });
                 inLink = false;
@@ -483,21 +568,67 @@ function inlineTokensToInline(tokens) {
             }
         }
         else if (token.type === "image") {
+            // The title (`![alt](src "Title")`) is kept: Cloudflare's pipeline
+            // renders a titled image as a figure with the title as its caption
+            // (256 on the corpus, "Figure 1: …"); dropped, the caption was lost.
+            const title = token.attrGet("title");
             push({
                 type: "image",
                 src: token.attrGet("src") || "",
                 alt: token.content || token.attrGet("alt") || "",
+                ...(title ? { title } : {}),
             });
         }
+        else if (token.type === "footnote_ref") {
+            const meta = (token.meta ?? {});
+            push({ type: "footnote-ref", label: meta.label ?? String((meta.id ?? 0) + 1) });
+        }
         else if (token.type === "html_inline") {
-            push({ type: "text", text: token.content });
+            // Raw inline HTML (`<br/>`, `<code>`, `<a href>`), not text: as a text
+            // node every serializer escaped it, and 749 Cloudflare pages showed
+            // literal `<br/>` and `<code>` to readers.
+            push({ type: "html-inline", html: token.content });
         }
         else if (token.type === "jsx_inline_self_closing" ||
             token.type === "jsx_inline_open" ||
             token.type === "jsx_inline_close") {
-            // Inline JSX tokens — skip (stripped components like <Render />)
+            // Inline JSX. A badge or a link button mid-sentence becomes its inline
+            // form (they were skipped: the badge's text and the button's href were
+            // simply gone). Other components are skipped, and a strip that loses
+            // content is REPORTED here too (once, at its opener).
+            const mapping = inlineContext?.componentMap[token.tag];
+            const attrs = (token.meta?.attrs ?? {});
+            if (mapping?.type === "badge" && token.type === "jsx_inline_self_closing") {
+                const props = mapping.propsFromAttrs?.(attrs) ?? {};
+                push({ type: "badge", text: String(props.text ?? ""), ...(props.variant ? { variant: String(props.variant) } : {}) });
+            }
+            else if (mapping?.type === "link-button" && token.type === "jsx_inline_open" && !inLink) {
+                linkHref = String(mapping.propsFromAttrs?.(attrs)?.href ?? "");
+                linkChildren = [];
+                inLink = true;
+                inlineButton = token.tag;
+            }
+            else if (token.type === "jsx_inline_close" && inLink && inlineButton === token.tag) {
+                result.push({ type: "link", href: linkHref, children: linkChildren });
+                inLink = false;
+                inlineButton = undefined;
+                linkHref = "";
+                linkChildren = [];
+            }
+            else if (token.type !== "jsx_inline_close" && mapping?.strip && !mapping.container && !mapping.silent) {
+                inlineContext?.onDrop?.(token.tag);
+            }
+            else if (token.type === "jsx_inline_self_closing" && mapping && !mapping.strip) {
+                // A block component (<YouTube>, <LinkCard>) written mid-line has no
+                // inline form: lost here, so say so.
+                inlineContext?.onDrop?.(token.tag);
+            }
         }
     }
+    // A <LinkButton> whose closer never came (another paragraph): its label
+    // and everything after it were buffered as link text and dropped.
+    if (inlineButton)
+        result.push(...linkChildren);
     return result;
 }
 // ── Post-processing ─────────────────────────────────────
@@ -542,6 +673,240 @@ function groupConsecutiveCards(tree) {
     flushCards();
     return result;
 }
+// ── Main entry point ────────────────────────────────────
+/**
+ * MDX reads the TEXT inside JSX/HTML elements as Markdown; a raw HTML block
+ * here is emitted as it is. Two Markdown forms in that text then broke the
+ * page: a code span (`` `Array<String>` `` in a `<td>` — the browser read
+ * `<String>` as a tag and the type vanished; 10 on the Cloudflare corpus) and
+ * a backslash escape (`Promise\<InstanceStatus>` inside `<code>` showed the
+ * backslash). Both become their HTML: `<code>` with escaped text, `&lt;`.
+ * Only TEXT between tags is touched — never inside a tag (attribute values)
+ * or inside `<pre>`, `<script>`, `<style>`.
+ */
+export function mdxHtmlText(html) {
+    if (!html.includes("`") && !html.includes("\\<"))
+        return html;
+    const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    let out = "";
+    let i = 0;
+    let raw = null; // inside <pre>/<script>/<style>: verbatim
+    while (i < html.length) {
+        const c = html[i];
+        // A code span first, as Markdown reads it: `Array<String>` holds a `<`
+        // that is NOT a tag.
+        if (c === "`" && raw === null) {
+            const run = /^`+/.exec(html.slice(i))[0];
+            const close = html.indexOf(run, i + run.length);
+            if (close > i && html[close + run.length] !== "`" && !html.slice(i + run.length, close).includes("\n\n")) {
+                let code = html.slice(i + run.length, close);
+                if (/^ .* $/s.test(code) && code.trim())
+                    code = code.slice(1, -1);
+                out += `<code>${esc(code)}</code>`;
+                i = close + run.length;
+                continue;
+            }
+            out += run;
+            i += run.length;
+            continue;
+        }
+        if (c === "\\" && html[i + 1] === "<" && raw === null) {
+            out += "&lt;";
+            i += 2;
+            continue;
+        }
+        if (c === "<") {
+            const m = /^<(\/?)([A-Za-z][\w-]*)\b(?:[^<>"']|"[^"]*"|'[^']*')*>/.exec(html.slice(i));
+            if (m) {
+                const name = m[2].toLowerCase();
+                if (raw === null && !m[1] && ["pre", "script", "style"].includes(name))
+                    raw = name;
+                else if (raw === name && m[1])
+                    raw = null;
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        out += c;
+        i++;
+    }
+    return out;
+}
+/**
+ * MDX has no HTML blocks: every tag line is its own JSX element. Markdown's
+ * HTML block runs to the next BLANK line, so a component written straight
+ * after a `<p>…</p>` line was swallowed into it and leaked as a tag
+ * (`<AnchorHeading>`, `<Aside>` in Cloudflare's JSX branches). A blank line
+ * goes between them — only after a line that is one COMPLETE element, so an
+ * open `<table>` or `<ul>` that the component sits inside is left whole.
+ */
+export function endHtmlBlocksAtComponents(source) {
+    const lines = source.split("\n");
+    let fence = null;
+    let prevComplete = false;
+    // Inside a multi-line template literal (`code={`…`}`) a blank line would
+    // change the value: an odd count of backticks on a line toggles it.
+    let inTemplate = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!fence && ((line.match(/(?<!\\)`/g)?.length ?? 0) % 2 === 1) && !/^[ \t]*(`{3,}|~{3,})/.test(line)) {
+            inTemplate = !inTemplate;
+            prevComplete = false;
+            continue;
+        }
+        if (inTemplate)
+            continue;
+        const m = /^[ \t]*(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            if (m && m[1][0] === fence[0] && m[1].length >= fence.length && line.trim() === m[1])
+                fence = null;
+            prevComplete = false;
+            continue;
+        }
+        if (m) {
+            fence = m[1];
+            prevComplete = false;
+            continue;
+        }
+        const t = line.trim();
+        if (prevComplete && /^<\/?[A-Z]/.test(t))
+            lines[i] = `\n${line}`;
+        // CommonMark type-6 names only: `<code>…</code>` on its own line is a
+        // paragraph line, not an HTML block, and must stay joined to its text.
+        const el = /^<(p|div|table|ul|ol|dl|pre|blockquote|h[1-6]|section|details|figure|hr|img)\b[^>]*>/.exec(t);
+        // A lone CLOSER of a block element (`</table>`) ends the element too: a
+        // component on the next line was swallowed by the HTML block
+        // (`<Aside>` after a raw table on the rules-language operators page).
+        // Whole blocks only: `</tr>` between rows would split a table.
+        const closer = /^<\/(p|div|table|ul|ol|dl|pre|blockquote|section|details|figure)\s*>$/.test(t);
+        prevComplete = closer || (!!el && (/\/>$/.test(el[0]) ? t === el[0] : new RegExp(`</${el[1]}\\s*>$`).test(t)));
+    }
+    return lines.join("\n");
+}
+/**
+ * `<Feature header="…"> Paid add-on` — text after a CONTAINER's opener on
+ * its line — is the start of the body in MDX. The block rule took the line
+ * as the opener and the text was lost with no report (web3: two plan badges).
+ * It moves to its own line, at the opener's indent. A component after the
+ * opener is `normalizeJsxLines`' job; a closer on the same line is an inline
+ * use and is left alone.
+ */
+export function splitContainerOpenerText(source, isContainer) {
+    let fence = null;
+    return source
+        .split("\n")
+        .map((line) => {
+        const f = /^[ \t]*(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            if (f && f[1][0] === fence[0] && f[1].length >= fence.length && line.trim() === f[1])
+                fence = null;
+            return line;
+        }
+        if (f) {
+            fence = f[1];
+            return line;
+        }
+        // `<Tabs syncKey='x'><TabItem label='CLI'>` and `</TabItem><TabItem …>`:
+        // ADJACENT container tags with no space between them are one line to
+        // the block rule, which took the first and lost the second (kv
+        // get-started lost five tab groups). Split them, containers only — an
+        // inline `<Badge>a</Badge><Badge>` must stay on its line.
+        // Only a line that STARTS with the tag (not prose, not a list marker),
+        // and never a table row or a line with a code span.
+        const tag = /<\/?([A-Z]\w*)\b(?:[^<>"'{]|"[^"]*"|'[^']*'|\{[^{}]*\})*>/g;
+        const parts = [];
+        let last = 0;
+        const splittable = /^[ \t]*<\/?[A-Z]/.test(line) && !/^[ \t]*\|/.test(line) && !line.includes("`");
+        for (let t = splittable ? tag.exec(line) : null; t; t = tag.exec(line)) {
+            const next = /^<\/?([A-Z]\w*)/.exec(line.slice(tag.lastIndex));
+            if (next && isContainer(t[1]) && isContainer(next[1]) && !/\/>$/.test(t[0])) {
+                parts.push(line.slice(last, tag.lastIndex));
+                last = tag.lastIndex;
+            }
+        }
+        if (parts.length) {
+            const indent = /^[ \t]*/.exec(line)[0];
+            // The last part may be an opener with text after it: that rule too.
+            return [...parts, openerText(indent + line.slice(last))].map((p, n) => (n ? (n === parts.length ? p : indent + p) : p)).join("\n");
+        }
+        return openerText(line);
+    })
+        .join("\n");
+    function openerText(line) {
+        const m = /^([ \t]*)<([A-Z]\w*)\b((?:[^<>"'{]|"[^"]*"|'[^']*'|\{[^{}]*\})*)>[ \t]*(\S.*)$/.exec(line);
+        if (!m || m[3].trimEnd().endsWith("/") || !isContainer(m[2]) || /^<\/?[A-Z]/.test(m[4]) || line.includes(`</${m[2]}>`))
+            return line;
+        return `${m[1]}<${m[2]}${m[3]}>\n${m[1]}${m[4]}`;
+    }
+}
+/**
+ * MDX (micromark with indented code off) opens AND closes a fence at any
+ * indentation; markdown-it refuses either one indented four or more past its
+ * container. Under a tab-indented list item that made every fence a
+ * paragraph — its code an inline span, its structure gone.
+ *
+ * This is markdown-it's fence rule with only those two refusals removed. It
+ * still ends at a line indented less than the CONTAINER (not the fence), and
+ * strips at most the opener's indent from each line, as micromark does. (An
+ * earlier version raised `blkIndent` to the opener's indent instead, which
+ * cut a fence short at any body line or closer indented less than its opener
+ * — and the orphaned closer then opened a fence that swallowed the item.)
+ */
+function acceptIndentedFences(md) {
+    const ruler = md.block.ruler;
+    const alt = ruler.__rules__.find((r) => r.name === "fence")?.alt ?? [];
+    md.block.ruler.at("fence", mdxFence, { alt });
+}
+function mdxFence(state, startLine, endLine, silent) {
+    let pos = state.bMarks[startLine] + state.tShift[startLine];
+    let max = state.eMarks[startLine];
+    if (pos + 3 > max)
+        return false;
+    const marker = state.src.charCodeAt(pos);
+    if (marker !== 0x7e /* ~ */ && marker !== 0x60 /* ` */)
+        return false;
+    let mem = pos;
+    pos = state.skipChars(pos, marker);
+    const len = pos - mem;
+    if (len < 3)
+        return false;
+    const markup = state.src.slice(mem, pos);
+    const params = state.src.slice(pos, max);
+    if (marker === 0x60 && params.includes("`"))
+        return false;
+    if (silent)
+        return true;
+    let nextLine = startLine;
+    let haveEndMarker = false;
+    for (;;) {
+        nextLine++;
+        if (nextLine >= endLine)
+            break;
+        pos = mem = state.bMarks[nextLine] + state.tShift[nextLine];
+        max = state.eMarks[nextLine];
+        // A non-empty line outdented past the container ends it (and the fence).
+        if (pos < max && state.sCount[nextLine] < state.blkIndent)
+            break;
+        if (state.src.charCodeAt(pos) !== marker)
+            continue;
+        pos = state.skipChars(pos, marker);
+        if (pos - mem < len)
+            continue;
+        pos = state.skipSpaces(pos);
+        if (pos < max)
+            continue;
+        haveEndMarker = true;
+        break;
+    }
+    state.line = nextLine + (haveEndMarker ? 1 : 0);
+    const token = state.push("fence", "code", 0);
+    token.info = params;
+    token.content = state.getLines(startLine + 1, nextLine, state.sCount[startLine], true);
+    token.markup = markup;
+    token.map = [startLine, state.line];
+    return true;
+}
 export function starlightToTree(source, options) {
     const adapter = options?.adapter;
     const onDrop = options?.onDrop;
@@ -551,32 +916,73 @@ export function starlightToTree(source, options) {
     // `---...---` as thematic-break + paragraph + thematic-break, which leaks the
     // YAML into the rendered body. Frontmatter is extracted separately at the
     // CLI level; here we only need to remove it from the content stream.
-    const { body } = extractFrontmatter(source);
+    const extracted = extractFrontmatter(source);
+    const body = extracted.body;
+    const frontmatter = options?.frontmatter ?? extracted.raw;
     // Pre-process source
     // Normalize tabs to spaces — MDX source often mixes tabs and spaces
     let cleaned = body.replace(/\t/g, "    ");
     // Resolve include/partial tags via adapter (e.g. Cloudflare's <Render>)
     if (adapter?.resolveIncludes) {
-        cleaned = adapter.resolveIncludes(cleaned, options?.partialsDir);
+        cleaned = adapter.resolveIncludes(cleaned, options?.partialsDir, options?.includeOptions, frontmatter);
     }
     cleaned = applyInlineTransforms(cleaned, adapter);
     cleaned = rewriteAssetPaths(cleaned);
     cleaned = convertDirectives(cleaned);
-    // Strip raw HTML div wrappers
-    cleaned = cleaned.replace(/<div[^>]*>\s*\n?/g, "");
-    cleaned = cleaned.replace(/<\/div>\s*\n?/g, "");
+    // Strip raw HTML div wrappers — outside code. A `<div>{value}</div>` in an
+    // Astro example lost its `</div>` AND the newline after it, which glued the
+    // closing fence to the code line, so the block swallowed the rest of the page.
+    cleaned = outsideFences(cleaned, (text) => text.replace(/<div[^>]*>\s*\n?/g, "").replace(/<\/div>\s*\n?/g, ""));
     // Normalize JSX lines — split multi-tag lines for the line-based parser
     cleaned = normalizeJsxLines(cleaned);
+    cleaned = endHtmlBlocksAtComponents(cleaned);
+    cleaned = splitContainerOpenerText(cleaned, (tag) => componentMap[tag]?.container === true);
     // Create markdown-it instance with JSX plugin
     // The plugin handles import stripping, JSX comments, and component tokenization
     const md = new MarkdownIt({ html: true, linkify: true }).use(mdxJsx, {
         components,
         selfClosing,
+        // `<Badge text="Beta" /> Connected meetings…` is a paragraph, as in MDX
+        // (the rest of such a line was dropped); inline components are handled or
+        // reported in inlineTokensToInline.
+        inlineWhenFollowedByText: true,
     });
+    // MDX has no indented code blocks (only fences). With the rule on, prose
+    // indented under a list item — common in Cloudflare's tab-indented sources —
+    // became a `plaintext` code block, and anything in it (a partial's include)
+    // showed literally.
+    md.disable("code");
+    acceptIndentedFences(md);
+    // GFM footnotes, as MDX (remark-gfm) reads them: `[^1]` + `[^1]: …`.
+    // Without the plugin a definition was a link REFERENCE definition, so
+    // `[^1]` became a link whose URL was the footnote's text. The `^[…]`
+    // inline sugar is not GFM, so it stays off.
+    md.use(mdFootnote);
+    md.inline.ruler.disable("footnote_inline");
     // Parse into tokens (including jsx_* tokens)
-    const tokens = md.parse(cleaned, {});
+    const env = {};
+    const tokens = md.parse(cleaned, env);
+    // GFM drops a definition nothing references, and so does the plugin. Say
+    // so: a reference inside raw HTML (`<td>…[^1]</td>`, which MDX reads as
+    // Markdown) is not seen here, and its note silently vanished.
+    for (const [key, id] of Object.entries(env.footnotes?.refs ?? {})) {
+        if (id === -1)
+            onDrop?.(`footnote [^${key.slice(1)}] with no reference`);
+    }
     // Convert tokens to tree
-    const tree = tokensToTree(tokens, componentMap, onDrop, describeComponent);
+    const outer = inlineContext;
+    inlineContext = { componentMap, onDrop };
+    let tree;
+    try {
+        tree = tokensToTree(tokens, componentMap, onDrop, describeComponent);
+    }
+    finally {
+        inlineContext = outer;
+    }
     const unwrapped = unwrapStepsOrderedList(tree);
-    return groupConsecutiveCards(unwrapped);
+    const grouped = groupConsecutiveCards(unwrapped);
+    const final = adapter?.transformTree ? adapter.transformTree(grouped) : grouped;
+    // Starlight's ids (github-slugger, per page): imported links target them.
+    assignHeadingSlugs(final);
+    return final;
 }