sourcey 3.4.4 → 3.4.7

package/dist/core/markdown-loader.js

@@ -3,7 +3,7 @@ import { basename, extname, relative } from "node:path";
 import { load as parseYaml } from "js-yaml";
 import { htmlId } from "../utils/html-id.js";
 import { renderIcon } from "../utils/icons.js";
-import { renderMarkdown, extractHeadings } from "../utils/markdown.js";
+import { renderCodeBlock, renderMarkdown, renderMarkdownInline, extractHeadings, } from "../utils/markdown.js";
 // ---------------------------------------------------------------------------
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
@@ -17,6 +17,11 @@ function parseFrontmatter(raw) {
     return { meta, body: match[2] };
 }
 const FENCED_BLOCK_TOKEN = "@@SOURCEY_FENCED_BLOCK_";
+const INLINE_CODE_TOKEN = "@@SOURCEY_INLINE_CODE_";
+/** Current page's protected fence blocks — used to restore placeholders in JSX children. */
+let activeFenceBlocks = [];
+/** Current page's protected inline code spans — used to restore placeholders in JSX children. */
+let activeInlineSpans = [];
 function protectFencedCodeBlocks(input) {
     const blocks = [];
     const output = [];
@@ -57,100 +62,509 @@ function protectFencedCodeBlocks(input) {
 function restoreFencedCodeBlocks(input, blocks) {
     return blocks.reduce((text, block, index) => text.replaceAll(`${FENCED_BLOCK_TOKEN}${index}@@`, block), input);
 }
-// ---------------------------------------------------------------------------
-// Component preprocessor: transforms MDX-style JSX components into HTML
-// ---------------------------------------------------------------------------
+function protectInlineCodeSpans(input) {
+    const spans = [];
+    let output = "";
+    let i = 0;
+    while (i < input.length) {
+        if (input[i] !== "`") {
+            output += input[i];
+            i += 1;
+            continue;
+        }
+        let tickEnd = i + 1;
+        while (tickEnd < input.length && input[tickEnd] === "`")
+            tickEnd += 1;
+        const delimiter = input.slice(i, tickEnd);
+        const closeIndex = input.indexOf(delimiter, tickEnd);
+        if (closeIndex === -1) {
+            output += input.slice(i);
+            break;
+        }
+        const span = input.slice(i, closeIndex + delimiter.length);
+        // If the content between delimiters spans multiple lines, it's a fenced
+        // code block (or block-level backticks), not an inline code span — skip it.
+        const inner = input.slice(tickEnd, closeIndex);
+        if (inner.includes("\n")) {
+            output += input[i];
+            i += 1;
+            continue;
+        }
+        const index = spans.push(span) - 1;
+        output += `${INLINE_CODE_TOKEN}${index}@@`;
+        i = closeIndex + delimiter.length;
+    }
+    return { text: output, spans };
+}
+function restoreInlineCodeSpans(input, spans) {
+    return spans.reduce((text, span, index) => text.replaceAll(`${INLINE_CODE_TOKEN}${index}@@`, span), input);
+}
+function skipWhitespace(input, index) {
+    let i = index;
+    while (i < input.length && /\s/.test(input[i]))
+        i += 1;
+    return i;
+}
+function parseQuotedAttrValue(input, index) {
+    const quote = input[index];
+    if (quote !== `"` && quote !== `'`)
+        return null;
+    let value = "";
+    let i = index + 1;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === "\\") {
+            if (i + 1 < input.length) {
+                value += input[i + 1];
+                i += 2;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === quote) {
+            return { value, nextIndex: i + 1 };
+        }
+        value += ch;
+        i += 1;
+    }
+    return null;
+}
+function parseBracedAttrValue(input, index) {
+    if (input[index] !== "{")
+        return null;
+    let depth = 1;
+    let i = index + 1;
+    while (i < input.length) {
+        const ch = input[i];
+        if (ch === `"` || ch === `'`) {
+            const quoted = parseQuotedAttrValue(input, i);
+            if (!quoted)
+                return null;
+            i = quoted.nextIndex;
+            continue;
+        }
+        if (ch === "{") {
+            depth += 1;
+        }
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return {
+                    value: input.slice(index + 1, i).trim(),
+                    nextIndex: i + 1,
+                };
+            }
+        }
+        i += 1;
+    }
+    return null;
+}
+function parseKeyValueAttrs(raw, options) {
+    const attrs = {};
+    let i = 0;
+    while (i < raw.length) {
+        i = skipWhitespace(raw, i);
+        if (i >= raw.length)
+            break;
+        const keyMatch = raw.slice(i).match(/^([A-Za-z_][A-Za-z0-9_-]*)/);
+        if (!keyMatch)
+            break;
+        const key = keyMatch[1];
+        i += key.length;
+        i = skipWhitespace(raw, i);
+        if (raw[i] !== "=")
+            break;
+        i += 1;
+        i = skipWhitespace(raw, i);
+        const parsedValue = raw[i] === "{" && options.allowBraces
+            ? parseBracedAttrValue(raw, i)
+            : parseQuotedAttrValue(raw, i);
+        if (!parsedValue)
+            break;
+        attrs[key] = parsedValue.value;
+        i = parsedValue.nextIndex;
+    }
+    return attrs;
+}
+const SUPPORTED_COMPONENT_TAGS = new Set([
+    "Steps",
+    "Step",
+    "CardGroup",
+    "Card",
+    "AccordionGroup",
+    "Accordion",
+    "Expandable",
+    "Tabs",
+    "Tab",
+    "CodeGroup",
+    "Note",
+    "Warning",
+    "Tip",
+    "Info",
+    "Video",
+    "Iframe",
+]);
+const SELF_CLOSING_COMPONENT_TAGS = new Set(["Video", "Iframe"]);
+function escapeDirectiveAttr(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function buildDirectiveAttrList(entries) {
+    const attrs = entries
+        .filter(([, value]) => value !== undefined && value !== "")
+        .map(([key, value]) => `${key}="${escapeDirectiveAttr(value)}"`);
+    return attrs.length > 0 ? `{${attrs.join(" ")}}` : "";
+}
+function indentBlock(text, prefix) {
+    const lines = text.split("\n");
+    const result = [];
+    let fence = null;
+    for (const line of lines) {
+        if (fence) {
+            // Inside a fenced code block — don't indent
+            result.push(line);
+            if (closesFence(line, fence))
+                fence = null;
+        }
+        else {
+            const nextFence = isFenceStart(line);
+            if (nextFence) {
+                // Fence opener — don't indent so markdown recognises it
+                fence = nextFence;
+                result.push(line);
+            }
+            else {
+                result.push(`${prefix}${line}`);
+            }
+        }
+    }
+    return result.join("\n");
+}
+function isWhitespaceOnlyText(node) {
+    return node.kind === "text" && node.value.trim() === "";
+}
+function findComponentTagEnd(input, start) {
+    let quote = null;
+    let braceDepth = 0;
+    let i = start + 1;
+    while (i < input.length) {
+        const ch = input[i];
+        if (quote) {
+            if (ch === "\\") {
+                i += 2;
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+            i += 1;
+            continue;
+        }
+        if (ch === `"` || ch === `'`) {
+            quote = ch;
+            i += 1;
+            continue;
+        }
+        if (ch === "{") {
+            braceDepth += 1;
+            i += 1;
+            continue;
+        }
+        if (ch === "}" && braceDepth > 0) {
+            braceDepth -= 1;
+            i += 1;
+            continue;
+        }
+        if (ch === ">" && braceDepth === 0) {
+            return i + 1;
+        }
+        i += 1;
+    }
+    return null;
+}
+function tryParseComponentTag(input, start) {
+    if (input[start] !== "<")
+        return null;
+    const end = findComponentTagEnd(input, start);
+    if (end === null)
+        return null;
+    const raw = input.slice(start, end);
+    const inner = input.slice(start + 1, end - 1).trim();
+    if (!inner)
+        return null;
+    if (inner.startsWith("/")) {
+        const closeName = inner.slice(1).trim();
+        if (!SUPPORTED_COMPONENT_TAGS.has(closeName))
+            return null;
+        return {
+            name: closeName,
+            kind: "close",
+            attrs: {},
+            raw,
+            start,
+            end,
+        };
+    }
+    const selfClosing = inner.endsWith("/");
+    const content = selfClosing ? inner.slice(0, -1).trimEnd() : inner;
+    const nameMatch = content.match(/^([A-Za-z][A-Za-z0-9]*)/);
+    if (!nameMatch || !SUPPORTED_COMPONENT_TAGS.has(nameMatch[1])) {
+        return null;
+    }
+    const name = nameMatch[1];
+    const attrSource = content.slice(name.length);
+    return {
+        name,
+        kind: selfClosing || SELF_CLOSING_COMPONENT_TAGS.has(name) ? "self" : "open",
+        attrs: parseKeyValueAttrs(attrSource, { allowBraces: true }),
+        raw,
+        start,
+        end,
+    };
+}
+function parseComponentNodes(input, startIndex = 0, untilTag) {
+    const nodes = [];
+    let cursor = startIndex;
+    while (cursor < input.length) {
+        const nextTag = input.indexOf("<", cursor);
+        if (nextTag === -1) {
+            if (cursor < input.length) {
+                nodes.push({ kind: "text", value: input.slice(cursor) });
+            }
+            return { nodes, nextIndex: input.length };
+        }
+        if (nextTag > cursor) {
+            nodes.push({ kind: "text", value: input.slice(cursor, nextTag) });
+        }
+        const tag = tryParseComponentTag(input, nextTag);
+        if (!tag) {
+            nodes.push({ kind: "text", value: "<" });
+            cursor = nextTag + 1;
+            continue;
+        }
+        if (tag.kind === "close") {
+            if (untilTag && tag.name === untilTag) {
+                return {
+                    nodes,
+                    nextIndex: tag.end,
+                    matchedClose: tag,
+                };
+            }
+            nodes.push({ kind: "text", value: tag.raw });
+            cursor = tag.end;
+            continue;
+        }
+        if (tag.kind === "self") {
+            nodes.push({
+                kind: "component",
+                name: tag.name,
+                attrs: tag.attrs,
+                children: [],
+                original: tag.raw,
+            });
+            cursor = tag.end;
+            continue;
+        }
+        const childResult = parseComponentNodes(input, tag.end, tag.name);
+        if (!childResult.matchedClose) {
+            nodes.push({
+                kind: "text",
+                value: input.slice(nextTag, childResult.nextIndex),
+            });
+            cursor = childResult.nextIndex;
+            continue;
+        }
+        nodes.push({
+            kind: "component",
+            name: tag.name,
+            attrs: tag.attrs,
+            children: childResult.nodes,
+            original: input.slice(nextTag, childResult.nextIndex),
+        });
+        cursor = childResult.nextIndex;
+    }
+    return { nodes, nextIndex: cursor };
+}
+function renderParsedComponentNodes(nodes) {
+    return nodes.map(renderParsedComponentNode).join("");
+}
+function collectChildComponents(children, expected) {
+    const matches = [];
+    for (const child of children) {
+        if (isWhitespaceOnlyText(child))
+            continue;
+        if (child.kind !== "component" || child.name !== expected) {
+            return null;
+        }
+        matches.push(child);
+    }
+    return matches;
+}
+/**
+ * Render the raw text content of parsed component children through the full
+ * markdown pipeline (component preprocessing → directive preprocessing →
+ * markdown rendering).  Strips common leading whitespace first so that
+ * indented JSX content (e.g. code fences inside <Step>) is handled correctly.
+ */
+function renderComponentChildrenToHtml(children) {
+    let raw = renderParsedComponentNodes(children);
+    raw = restoreFencedCodeBlocks(raw, activeFenceBlocks);
+    raw = restoreInlineCodeSpans(raw, activeInlineSpans);
+    return renderDirectiveMarkdown(dedent(raw));
+}
+/**
+ * Strip common leading whitespace from a block of text.
+ */
+function dedent(text) {
+    const lines = text.split("\n");
+    const nonEmpty = lines.filter((l) => l.trim().length > 0);
+    if (nonEmpty.length === 0)
+        return text;
+    const indent = Math.min(...nonEmpty.map((l) => l.match(/^(\s*)/)?.[1].length ?? 0));
+    if (indent === 0)
+        return text;
+    return lines.map((l) => l.slice(indent)).join("\n");
+}
+/**
+ * Render an accordion from a parsed JSX component directly to HTML.
+ */
+function renderComponentAccordion(node) {
+    const title = renderMarkdownInline(node.attrs.title || "").trim();
+    const body = renderComponentChildrenToHtml(node.children);
+    return `<details class="accordion-item">
+<summary class="accordion-trigger">${title}</summary>
+<div class="accordion-content">
+${body}
+</div>
+</details>`;
+}
+/**
+ * Render a parsed JSX component directly to final HTML.
+ * Returns null if the component structure is invalid (falls back to raw text).
+ */
+function renderParsedComponentElement(node) {
+    if (node.name === "Steps") {
+        const steps = collectChildComponents(node.children, "Step");
+        if (!steps)
+            return null;
+        const items = steps
+            .map((step, index) => {
+            const title = renderMarkdownInline(step.attrs.title || "").trim();
+            const body = renderComponentChildrenToHtml(step.children);
+            return `<div role="listitem" class="step-item">
+<div class="step-number">${index + 1}</div>
+<div class="step-body">
+<p class="step-title">${title}</p>
+<div class="step-content">
+${body}
+</div>
+</div>
+</div>`;
+        })
+            .join("\n");
+        return `\n\n<div role="list" class="steps not-prose">\n${items}\n</div>\n`;
+    }
+    if (node.name === "CardGroup") {
+        const cards = collectChildComponents(node.children, "Card");
+        if (!cards)
+            return null;
+        const cols = node.attrs.cols || "2";
+        const cardHtml = cards
+            .map((card) => {
+            const tag = card.attrs.href ? "a" : "div";
+            const href = card.attrs.href ? ` href="${escapeHtmlAttr(card.attrs.href)}"` : "";
+            const iconHtml = renderIcon(card.attrs.icon || "");
+            const title = renderMarkdownInline(card.attrs.title || "").trim();
+            const body = renderComponentChildrenToHtml(card.children);
+            return `<${tag}${href} class="card-item">
+<div class="card-item-inner">
+${iconHtml}
+<h3 class="card-item-title">${title}</h3>
+<div class="card-item-content">
+${body}
+</div>
+</div>
+</${tag}>`;
+        })
+            .join("\n");
+        return `\n\n<div class="card-group not-prose" data-cols="${escapeHtmlAttr(cols)}">\n${cardHtml}\n</div>\n`;
+    }
+    if (node.name === "AccordionGroup") {
+        const accordions = collectChildComponents(node.children, "Accordion");
+        if (!accordions)
+            return null;
+        return `\n\n<div class="accordion-group not-prose">\n${accordions.map(renderComponentAccordion).join("\n")}\n</div>\n`;
+    }
+    if (node.name === "Accordion" || node.name === "Expandable") {
+        return `\n\n${renderComponentAccordion(node)}\n`;
+    }
+    if (node.name === "Tabs") {
+        const tabs = collectChildComponents(node.children, "Tab");
+        if (!tabs)
+            return null;
+        const tabData = tabs.map((tab) => ({
+            title: renderMarkdownInline(tab.attrs.title || "").trim(),
+            body: renderComponentChildrenToHtml(tab.children),
+        }));
+        return `\n\n${buildTabbedHtml(tabData, nextId("tabs"))}\n`;
+    }
+    if (node.name === "CodeGroup") {
+        let cgRaw = renderParsedComponentNodes(node.children);
+        cgRaw = restoreFencedCodeBlocks(cgRaw, activeFenceBlocks);
+        cgRaw = restoreInlineCodeSpans(cgRaw, activeInlineSpans);
+        const codeBlocks = parseTitledCodeBlocks(dedent(cgRaw)).map((block) => ({
+            title: renderMarkdownInline(block.title).trim(),
+            body: renderCodeBlock(block.body, block.lang),
+        }));
+        if (codeBlocks.length === 0)
+            return null;
+        return `\n\n${buildTabbedHtml(codeBlocks, nextId("cg"), "directive-code-group")}\n`;
+    }
+    if (node.name === "Note" || node.name === "Warning" || node.name === "Tip" || node.name === "Info") {
+        const type = node.name.toLowerCase();
+        const label = renderMarkdownInline(node.attrs.title?.trim() || node.name.charAt(0).toUpperCase() + node.name.slice(1)).trim();
+        const body = renderComponentChildrenToHtml(node.children);
+        return `\n\n<div class="callout callout-${type} not-prose">
+<div class="callout-title">${label}</div>
+${body ? `<div class="callout-content">\n${body}\n</div>` : ""}
+</div>\n`;
+    }
+    if (node.name === "Video") {
+        const titleAttr = node.attrs.title ? `{title="${escapeDirectiveAttr(node.attrs.title)}"}` : "";
+        return `::video[${node.attrs.src || ""}]${titleAttr}`;
+    }
+    if (node.name === "Iframe") {
+        const attrString = buildDirectiveAttrList([
+            ["title", node.attrs.title],
+            ["height", node.attrs.height],
+        ]);
+        return `::iframe[${node.attrs.src || ""}]${attrString}`;
+    }
+    return null;
+}
+function renderParsedComponentNode(node) {
+    if (node.kind === "text")
+        return node.value;
+    return renderParsedComponentElement(node) ?? node.original;
+}
 /**
  * Convert JSX-style components to directive syntax so they go through
  * a single rendering path in preprocessDirectives.
  */
 function preprocessComponents(body) {
-    const { text, blocks } = protectFencedCodeBlocks(body);
-    let html = text;
-    // <Steps> <Step title="...">content</Step> ... </Steps> → :::steps numbered list
-    html = html.replace(/<Steps>\s*([\s\S]*?)\s*<\/Steps>/g, (_m, inner) => {
-        const steps = [];
-        inner.replace(/\s*<Step\s+title="([^"]*)">\s*([\s\S]*?)\s*<\/Step>/g, (_sm, title, content) => {
-            steps.push({ title, content: content.trim() });
-            return "";
-        });
-        const list = steps
-            .map((s, i) => `${i + 1}. ${s.title}\n   ${s.content}`)
-            .join("\n");
-        return `:::steps\n${list}\n:::`;
-    });
-    // <CardGroup cols={N}> <Card ...> ... </Card> ... </CardGroup> → :::card-group
-    html = html.replace(/<CardGroup\s+cols=\{(\d+)\}>\s*([\s\S]*?)\s*<\/CardGroup>/g, (_m, cols, inner) => {
-        const cards = inner.replace(/\s*<Card\s+title="([^"]*)"\s+icon="([^"]*)"(?:\s+href="([^"]*)")?\s*>\s*([\s\S]*?)\s*<\/Card>/g, (_cm, title, icon, href, content) => {
-            const hrefAttr = href ? ` href="${href}"` : "";
-            return `\n::card{title="${title}" icon="${icon}"${hrefAttr}}\n${content.trim()}\n::`;
-        }).trim();
-        return `:::card-group{cols="${cols}"}\n${cards}\n:::`;
-    });
-    // <AccordionGroup> <Accordion ...> ... </AccordionGroup> → wrap in accordion-group
-    html = html.replace(/<AccordionGroup>\s*([\s\S]*?)\s*<\/AccordionGroup>/g, (_m, inner) => {
-        const items = inner.replace(/\s*<Accordion\s+title="([^"]*)">\s*([\s\S]*?)\s*<\/Accordion>/g, (_am, title, content) => {
-            return `\n:::accordion{title="${title}"}\n${content.trim()}\n:::`;
-        }).trim();
-        return `<div class="accordion-group not-prose">\n${items}\n</div>`;
-    });
-    // Standalone <Accordion> outside of group
-    html = html.replace(/<Accordion\s+title="([^"]*)">\s*([\s\S]*?)\s*<\/Accordion>/g, (_m, title, content) => {
-        return `:::accordion{title="${title}"}\n${content.trim()}\n:::`;
-    });
-    // <Tabs> <Tab title="...">content</Tab> ... </Tabs> → :::tabs with ::tab children
-    html = html.replace(/<Tabs>\s*([\s\S]*?)\s*<\/Tabs>/g, (_m, inner) => {
-        const tabs = [];
-        inner.replace(/\s*<Tab\s+title="([^"]*)">\s*([\s\S]*?)\s*<\/Tab>/g, (_tm, title, content) => {
-            tabs.push(`::tab{title="${title}"}\n${content.trim()}\n::`);
-            return "";
-        });
-        return `:::tabs\n${tabs.join("\n")}\n:::`;
-    });
-    // <CodeGroup> with titled fenced code blocks → :::code-group
-    html = html.replace(/<CodeGroup>\s*([\s\S]*?)\s*<\/CodeGroup>/g, (_m, inner) => `:::code-group\n${inner.trim()}\n:::`);
-    // <Note>, <Warning>, <Tip>, <Info> → :::callout directives
-    for (const type of ["note", "warning", "tip", "info"]) {
-        const tag = type.charAt(0).toUpperCase() + type.slice(1);
-        html = html.replace(new RegExp(`<${tag}(?:\\s+title="([^"]*)")?\\s*>\\s*([\\s\\S]*?)\\s*<\\/${tag}>`, "g"), (_m, title, content) => {
-            const titleSuffix = title ? ` ${title}` : "";
-            return `:::${type}${titleSuffix}\n${content.trim()}\n:::`;
-        });
-    }
-    // <Video src="..." title="..." /> → ::video[url]{title="..."}
-    html = html.replace(/<Video\s+([^>]*?)\s*\/?\s*>/g, (_m, attrs) => {
-        const src = attrs.match(/src="([^"]*)"/)?.[1] ?? "";
-        const title = attrs.match(/title="([^"]*)"/)?.[1];
-        const titleAttr = title ? `{title="${title}"}` : "";
-        return `::video[${src}]${titleAttr}`;
-    });
-    // <Iframe src="..." title="..." height="..." /> → ::iframe[url]{attrs}
-    html = html.replace(/<Iframe\s+([^>]*?)\s*\/?\s*>/g, (_m, attrs) => {
-        const src = attrs.match(/src="([^"]*)"/)?.[1] ?? "";
-        const title = attrs.match(/title="([^"]*)"/)?.[1];
-        const height = attrs.match(/height="([^"]*)"/)?.[1];
-        const parts = [];
-        if (title)
-            parts.push(`title="${title}"`);
-        if (height)
-            parts.push(`height="${height}"`);
-        const attrStr = parts.length ? `{${parts.join(" ")}}` : "";
-        return `::iframe[${src}]${attrStr}`;
-    });
-    return restoreFencedCodeBlocks(html, blocks);
+    const { text: fencedText, blocks } = protectFencedCodeBlocks(body);
+    activeFenceBlocks = blocks;
+    const { text, spans } = protectInlineCodeSpans(fencedText);
+    activeInlineSpans = spans;
+    const parsed = parseComponentNodes(text);
+    const restoredInline = restoreInlineCodeSpans(renderParsedComponentNodes(parsed.nodes), spans);
+    return restoreFencedCodeBlocks(restoredInline, blocks);
 }
 // ---------------------------------------------------------------------------
 // Directive preprocessor: transforms :::directive blocks into HTML
 // ---------------------------------------------------------------------------
 /** Parse {key="value" key2="value2"} attribute strings. */
 function parseAttrs(raw) {
-    const attrs = {};
-    if (!raw)
-        return attrs;
-    for (const m of raw.matchAll(/(\w+)="([^"]*)"/g)) {
-        attrs[m[1]] = m[2];
-    }
-    return attrs;
+    return parseKeyValueAttrs(raw, { allowBraces: false });
 }
 /** Deterministic tab-group ID; reset per page. */
 let directiveCounter = 0;
@@ -161,6 +575,31 @@ function nextId(prefix) {
 function resetDirectiveCounter() {
     directiveCounter = 0;
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeHtmlAttr(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;");
+}
+function stripDirectiveIndent(line) {
+    return line.replace(/^ {0,3}/, "");
+}
+function isFenceStart(line) {
+    const match = stripDirectiveIndent(line).match(/^(`{3,}|~{3,})(.*)$/);
+    if (!match)
+        return null;
+    return { char: match[1][0], length: match[1].length };
+}
+function closesFence(line, fence) {
+    const match = stripDirectiveIndent(line).match(/^(`{3,}|~{3,})(.*)$/);
+    return !!(match &&
+        match[1][0] === fence.char &&
+        match[1].length >= fence.length &&
+        !match[2].trim());
+}
 /** Build tabbed UI HTML (shared by :::tabs and :::code-group). */
 function buildTabbedHtml(tabs, id, extraClass) {
     const cls = extraClass
@@ -187,146 +626,316 @@ ${panels}
  */
 function splitChildren(content, marker) {
     const children = [];
-    const parts = content.split(new RegExp(`^\\s*::${marker}`, "gm"));
-    for (const part of parts) {
-        if (!part.trim())
+    const lines = content.split("\n");
+    const startRe = new RegExp(`^::${escapeRegExp(marker)}(?:\\{([^}]*)\\})?\\s*$`);
+    let i = 0;
+    while (i < lines.length) {
+        const start = stripDirectiveIndent(lines[i]).trimEnd().match(startRe);
+        if (!start) {
+            i += 1;
             continue;
-        const m = part.match(/^\{([^}]*)\}\s*\n?([\s\S]*)/);
-        if (m) {
-            // Strip trailing :: child-close marker
-            const body = m[2].trim().replace(/\n?::$/m, "").trim();
-            children.push({ attrs: parseAttrs(m[1]), body });
         }
+        let fence = null;
+        let depth = 1;
+        let j = i + 1;
+        while (j < lines.length) {
+            const line = lines[j];
+            if (fence) {
+                if (closesFence(line, fence))
+                    fence = null;
+                j += 1;
+                continue;
+            }
+            const nextFence = isFenceStart(line);
+            if (nextFence) {
+                fence = nextFence;
+                j += 1;
+                continue;
+            }
+            const stripped = stripDirectiveIndent(line).trimEnd();
+            if (startRe.test(stripped)) {
+                depth += 1;
+            }
+            else if (/^::\s*$/.test(stripped)) {
+                depth -= 1;
+                if (depth === 0)
+                    break;
+            }
+            j += 1;
+        }
+        if (depth !== 0) {
+            i += 1;
+            continue;
+        }
+        children.push({
+            attrs: parseAttrs(start[1] ?? ""),
+            body: lines.slice(i + 1, j).join("\n").trim(),
+        });
+        i = j + 1;
     }
     return children;
 }
-/**
- * Process :::directive blocks. Handles callouts, steps, tabs,
- * code-group, card-group, and accordion.
- *
- * Matching strategy: process one block type at a time. Each regex
- * matches a specific `:::type` opener so closing `:::` markers
- * from other directive types cannot collide.
- */
-function preprocessDirectives(body) {
-    const { text, blocks } = protectFencedCodeBlocks(body);
-    let html = text;
-    // Callouts: :::note, :::warning, :::tip, :::info (optional title)
-    html = html.replace(/^:::(note|warning|tip|info)(?:[^\S\n]+(.+))?\s*\n([\s\S]*?)^:::\s*$/gm, (_m, type, title, content) => {
-        const label = title?.trim() || type.charAt(0).toUpperCase() + type.slice(1);
-        const body = content.trim();
+function parseTitledCodeBlocks(content) {
+    const blocks = [];
+    const lines = content.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = stripDirectiveIndent(lines[i]).trimEnd();
+        const open = line.match(/^(`{3,}|~{3,})(\S+)?(?:\s+title="([^"]*)"|\s+(.+?))?\s*$/);
+        if (!open) {
+            i += 1;
+            continue;
+        }
+        const fence = { char: open[1][0], length: open[1].length };
+        let j = i + 1;
+        while (j < lines.length && !closesFence(lines[j], fence))
+            j += 1;
+        if (j >= lines.length)
+            break;
+        blocks.push({
+            title: open[3] ?? open[4] ?? "",
+            lang: open[2] ?? "",
+            body: lines.slice(i + 1, j).join("\n"),
+        });
+        i = j + 1;
+    }
+    return blocks;
+}
+const SUPPORTED_DIRECTIVES = new Set([
+    "note",
+    "warning",
+    "tip",
+    "info",
+    "steps",
+    "tabs",
+    "code-group",
+    "card-group",
+    "accordion",
+]);
+function matchDirectiveStart(line) {
+    const match = stripDirectiveIndent(line).trimEnd().match(/^:::(\w[\w-]*)(.*)$/);
+    if (!match || !SUPPORTED_DIRECTIVES.has(match[1]))
+        return null;
+    return {
+        type: match[1],
+        meta: match[2].trim(),
+    };
+}
+function isAnyDirectiveStart(line) {
+    return /^:::\w[\w-]*(?:\{[^}]*\}|.*)?$/.test(stripDirectiveIndent(line).trimEnd());
+}
+function renderDirectiveMarkdown(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return "";
+    return renderMarkdown(preprocessDirectives(preprocessComponents(trimmed))).trim();
+}
+function collectDirectiveBlock(lines, startIndex) {
+    let fence = null;
+    let depth = 1;
+    let i = startIndex + 1;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (fence) {
+            if (closesFence(line, fence))
+                fence = null;
+            i += 1;
+            continue;
+        }
+        const nextFence = isFenceStart(line);
+        if (nextFence) {
+            fence = nextFence;
+            i += 1;
+            continue;
+        }
+        const stripped = stripDirectiveIndent(line).trimEnd();
+        if (isAnyDirectiveStart(stripped)) {
+            depth += 1;
+        }
+        else if (/^:::\s*$/.test(stripped)) {
+            depth -= 1;
+            if (depth === 0) {
+                return {
+                    content: lines.slice(startIndex + 1, i).join("\n"),
+                    nextLine: i + 1,
+                };
+            }
+        }
+        i += 1;
+    }
+    return null;
+}
+function renderDirectiveBlock(type, meta, content) {
+    if (type === "note" || type === "warning" || type === "tip" || type === "info") {
+        const label = renderMarkdownInline(meta.trim() || type.charAt(0).toUpperCase() + type.slice(1)).trim();
+        const body = renderDirectiveMarkdown(content);
         return `\n\n<div class="callout callout-${type} not-prose">
 <div class="callout-title">${label}</div>
-${body ? `<div class="callout-content">\n\n${body}\n\n</div>` : ""}
-</div>\n\n`;
-    });
-    // Steps: :::steps with a plain numbered list inside
-    html = html.replace(/^:::steps\s*\n([\s\S]*?)^:::\s*$/gm, (_m, content) => {
+${body ? `<div class="callout-content">\n${body}\n</div>` : ""}
+</div>\n`;
+    }
+    if (type === "steps") {
         const lines = content.trim().split("\n");
         const steps = [];
-        let fenceMarker = "";
+        let fence = null;
         for (const line of lines) {
-            // Track fenced code blocks so we don't mis-detect numbered
-            // lines inside them as step titles.  A closing fence must use
-            // the same character, at least as many repeats, and no info string.
-            const stripped = line.replace(/^ {1,3}/, "");
-            const fm = stripped.match(/^(`{3,}|~{3,})(.*)/);
-            if (fm) {
-                if (!fenceMarker) {
-                    fenceMarker = fm[1];
-                }
-                else if (fm[1][0] === fenceMarker[0] &&
-                    fm[1].length >= fenceMarker.length &&
-                    !fm[2].trim()) {
-                    fenceMarker = "";
+            if (fence) {
+                if (closesFence(line, fence))
+                    fence = null;
+            }
+            else {
+                const nextFence = isFenceStart(line);
+                if (nextFence) {
+                    fence = nextFence;
                 }
             }
-            const sm = !fenceMarker && line.match(/^\d+\.\s+(.+)/);
-            if (sm) {
-                steps.push({ title: sm[1], body: [] });
+            const stripped = line.replace(/^ {1,3}/, "");
+            const stepMatch = !fence && line.match(/^\d+\.\s+(.+)/);
+            if (stepMatch) {
+                steps.push({ title: stepMatch[1], body: [] });
             }
             else if (steps.length > 0) {
-                // Strip up to 3 leading spaces (markdown list indent)
                 steps[steps.length - 1].body.push(stripped);
             }
         }
+        if (steps.length === 0)
+            return renderDirectiveMarkdown(content);
         const items = steps
-            .map((s, i) => `<div role="listitem" class="step-item">
-<div class="step-number">${i + 1}</div>
+            .map((step, index) => {
+            const title = renderMarkdownInline(step.title).trim();
+            const body = renderDirectiveMarkdown(step.body.join("\n").trim());
+            return `<div role="listitem" class="step-item">
+<div class="step-number">${index + 1}</div>
 <div class="step-body">
-<p class="step-title">${s.title}</p>
+<p class="step-title">${title}</p>
 <div class="step-content">
-
-${s.body.join("\n").trim()}
-
+${body}
 </div>
 </div>
-</div>`)
+</div>`;
+        })
             .join("\n");
-        return `\n\n<div role="list" class="steps not-prose">\n${items}\n</div>\n\n`;
-    });
-    // Tabs: :::tabs with ::tab{title="..."} children
-    html = html.replace(/^:::tabs\s*\n([\s\S]*?)^:::\s*$/gm, (_m, content) => {
-        const tabs = splitChildren(content, "tab").map((c) => ({
-            title: c.attrs.title || "",
-            body: c.body,
+        return `\n\n<div role="list" class="steps not-prose">\n${items}\n</div>\n`;
+    }
+    if (type === "tabs") {
+        const tabs = splitChildren(content, "tab").map((child) => ({
+            title: renderMarkdownInline(child.attrs.title || "").trim(),
+            body: renderDirectiveMarkdown(child.body),
+        }));
+        if (tabs.length === 0)
+            return renderDirectiveMarkdown(content);
+        return `\n\n${buildTabbedHtml(tabs, nextId("tabs"))}\n`;
+    }
+    if (type === "code-group") {
+        const codeBlocks = parseTitledCodeBlocks(content).map((block) => ({
+            title: renderMarkdownInline(block.title).trim(),
+            body: renderCodeBlock(block.body, block.lang),
         }));
-        return `\n\n${buildTabbedHtml(tabs, nextId("tabs"))}\n\n`;
-    });
-    // Code Group: :::code-group with titled fenced code blocks
-    html = html.replace(/^:::code-group\s*\n([\s\S]*?)^:::\s*$/gm, (_m, content) => {
-        const restoredContent = restoreFencedCodeBlocks(content, blocks);
-        const codeBlocks = [];
-        const re = /```(\w+)\s+title="([^"]*)"\s*\n([\s\S]*?)```/g;
-        let match;
-        while ((match = re.exec(restoredContent)) !== null) {
-            codeBlocks.push({ title: match[2], body: `\`\`\`${match[1]}\n${match[3]}\`\`\`` });
-        }
         if (codeBlocks.length === 0)
-            return restoredContent;
-        return `\n\n${buildTabbedHtml(codeBlocks, nextId("cg"), "directive-code-group")}\n\n`;
-    });
-    // Card Group: :::card-group{cols="N"} with ::card children
-    html = html.replace(/^:::card-group(?:\{([^}]*)\})?\s*\n([\s\S]*?)^:::\s*$/gm, (_m, attrsRaw, content) => {
-        const cols = parseAttrs(attrsRaw || "").cols || "2";
-        const cards = splitChildren(content, "card").map((c) => {
-            const tag = c.attrs.href ? "a" : "div";
-            const href = c.attrs.href ? ` href="${c.attrs.href}"` : "";
-            const iconHtml = renderIcon(c.attrs.icon || "");
+            return renderDirectiveMarkdown(content);
+        return `\n\n${buildTabbedHtml(codeBlocks, nextId("cg"), "directive-code-group")}\n`;
+    }
+    if (type === "card-group") {
+        const cols = parseAttrs(meta.match(/^\{([^}]*)\}$/)?.[1] ?? "").cols || "2";
+        const cards = splitChildren(content, "card").map((child) => {
+            const tag = child.attrs.href ? "a" : "div";
+            const href = child.attrs.href ? ` href="${escapeHtmlAttr(child.attrs.href)}"` : "";
+            const iconHtml = renderIcon(child.attrs.icon || "");
+            const title = renderMarkdownInline(child.attrs.title || "").trim();
+            const body = renderDirectiveMarkdown(child.body);
             return `<${tag}${href} class="card-item">
 <div class="card-item-inner">
 ${iconHtml}
-<h3 class="card-item-title">${c.attrs.title || ""}</h3>
+<h3 class="card-item-title">${title}</h3>
 <div class="card-item-content">
-
-${c.body}
-
+${body}
 </div>
 </div>
 </${tag}>`;
         });
-        return `\n\n<div class="card-group not-prose" data-cols="${cols}">\n${cards.join("\n")}\n</div>\n\n`;
-    });
-    // Accordion: :::accordion{title="..."}
-    html = html.replace(/^:::accordion(?:\{([^}]*)\})?\s*\n([\s\S]*?)^:::\s*$/gm, (_m, attrsRaw, content) => {
-        const title = parseAttrs(attrsRaw || "").title || "";
-        return `\n\n<details class="accordion-item">
+        if (cards.length === 0)
+            return renderDirectiveMarkdown(content);
+        return `\n\n<div class="card-group not-prose" data-cols="${escapeHtmlAttr(cols)}">\n${cards.join("\n")}\n</div>\n`;
+    }
+    const title = renderMarkdownInline(parseAttrs(meta.match(/^\{([^}]*)\}$/)?.[1] ?? "").title || "").trim();
+    const body = renderDirectiveMarkdown(content);
+    return `\n\n<details class="accordion-item">
 <summary class="accordion-trigger">${title}</summary>
 <div class="accordion-content">
-
-${content.trim()}
-
+${body}
 </div>
-</details>\n\n`;
-    });
-    // Auto-wrap consecutive accordion items in an accordion-group (skip already-wrapped)
-    html = html.replace(/(<details class="accordion-item">[\s\S]*?<\/details>\s*){2,}/g, (match, _p1, offset) => {
-        const before = html.slice(Math.max(0, offset - 40), offset);
-        if (before.includes("accordion-group"))
-            return match;
-        return `<div class="accordion-group not-prose">\n${match.trim()}\n</div>`;
-    });
-    return restoreFencedCodeBlocks(html, blocks);
+</details>\n`;
+}
+/**
+ * Process :::directive blocks. Handles callouts, steps, tabs,
+ * code-group, card-group, and accordion.
+ *
+ * Matching strategy: process one block type at a time. Each regex
+ * matches a specific `:::type` opener so closing `:::` markers
+ * from other directive types cannot collide.
+ */
+function preprocessDirectives(body) {
+    const lines = body.split("\n");
+    const out = [];
+    let i = 0;
+    let fence = null;
+    while (i < lines.length) {
+        if (fence) {
+            out.push(lines[i]);
+            if (closesFence(lines[i], fence))
+                fence = null;
+            i += 1;
+            continue;
+        }
+        const nextFence = isFenceStart(lines[i]);
+        if (nextFence) {
+            fence = nextFence;
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        const start = matchDirectiveStart(lines[i]);
+        if (!start) {
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        if (start.type === "accordion") {
+            const accordions = [];
+            let nextLine = i;
+            while (true) {
+                const accordionStart = matchDirectiveStart(lines[nextLine]);
+                if (!accordionStart || accordionStart.type !== "accordion")
+                    break;
+                const accordionBlock = collectDirectiveBlock(lines, nextLine);
+                if (!accordionBlock)
+                    break;
+                accordions.push(renderDirectiveBlock("accordion", accordionStart.meta, accordionBlock.content));
+                nextLine = accordionBlock.nextLine;
+                let scan = nextLine;
+                while (scan < lines.length && /^\s*$/.test(lines[scan]))
+                    scan += 1;
+                const nextAccordion = scan < lines.length ? matchDirectiveStart(lines[scan]) : null;
+                if (!nextAccordion || nextAccordion.type !== "accordion")
+                    break;
+                nextLine = scan;
+            }
+            if (accordions.length > 1) {
+                out.push(`\n\n<div class="accordion-group not-prose">\n${accordions.join("\n")}\n</div>\n`);
+                i = nextLine;
+                continue;
+            }
+        }
+        const block = collectDirectiveBlock(lines, i);
+        if (!block) {
+            out.push(lines[i]);
+            i += 1;
+            continue;
+        }
+        out.push(renderDirectiveBlock(start.type, start.meta, block.content));
+        i = block.nextLine;
+    }
+    return out.join("\n");
 }
 // ---------------------------------------------------------------------------
 // Public API
@@ -338,14 +947,24 @@ export async function loadMarkdownPage(filePath, slug) {
     const raw = await readFile(filePath, "utf-8");
     const { meta, body } = parseFrontmatter(raw);
     resetDirectiveCounter();
-    const preprocessed = preprocessDirectives(preprocessComponents(body));
-    const headings = extractHeadings(preprocessed);
+    const componentPreprocessed = preprocessComponents(body);
+    const preprocessed = preprocessDirectives(componentPreprocessed);
+    const headings = extractHeadings(componentPreprocessed);
     const html = renderMarkdown(preprocessed);
-    const title = meta.title ?? extractFirstHeading(preprocessed) ?? slug;
+    const title = meta.title ?? extractFirstHeading(componentPreprocessed) ?? slug;
     const description = meta.description ?? "";
     // Strip leading h1 from rendered HTML when it duplicates the page title
     const cleanHtml = html.replace(/^\s*<h1[^>]*>(.*?)<\/h1>\s*/i, (_m, inner) => inner.replace(/<[^>]+>/g, "").trim() === title ? "" : _m);
-    return { title, description, slug, html: cleanHtml, headings, sourcePath: relative(process.cwd(), filePath) };
+    const sourcePath = relative(process.cwd(), filePath);
+    return {
+        title,
+        description,
+        slug,
+        html: cleanHtml,
+        headings,
+        sourcePath,
+        editPath: sourcePath,
+    };
 }
 /**
  * Extract the first # heading from markdown as a fallback title.