@dogsbay/markdown-it-mdx-jsx 0.2.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * markdown-it-mdx-jsx — MDX/JSX component support for markdown-it.
+ *
+ * Dual-context parser following the micromark-extension-mdx-jsx architecture:
+ * - Block rule (flow): handles JSX tags at the start of lines, loops to process
+ *   multiple tags per line, recursively tokenizes inner content
+ * - Inline rule (text): handles JSX tags within prose (self-closing, open, close)
+ *
+ * Components are identified by uppercase first letter (React convention).
+ * Emits `jsx_open`, `jsx_close`, `jsx_self_closing` tokens at block level,
+ * and `jsx_inline_open`, `jsx_inline_close`, `jsx_inline_self_closing` at inline level.
+ */
+import type MarkdownIt from "markdown-it";
+export interface MdxJsxOptions {
+    /** Recognized component names. If omitted, any uppercase tag is recognized. */
+    components?: string[];
+    /** Tags that are always self-closing even without `/>`. */
+    selfClosing?: string[];
+}
+/**
+ * Parse JSX-style attributes from a string.
+ * Handles: key="value", key='value', key={expr}, key={{obj}}, bare key.
+ * Uses brace-depth tracking for JSX expressions.
+ */
+export declare function parseJsxAttrs(str: string): Record<string, string>;
+/**
+ * Normalize JSX source for line-based parsing.
+ *
+ * markdown-it processes blocks line-by-line. JSX patterns with multiple
+ * tags on one line (common in Cloudflare/Starlight source) need to be
+ * split so each tag starts on its own line.
+ *
+ * Patterns handled:
+ * - `</TabItem> <TabItem>` → two lines
+ * - `<Tabs> <TabItem>` → two lines
+ * - `</TabItem> </Tabs>` → two lines
+ *
+ * Exported so consumers can call it before md.parse() if needed.
+ */
+export declare function normalizeJsxLines(source: string): string;
+export default function mdxJsxPlugin(md: MarkdownIt, options?: MdxJsxOptions): void;
+export { mdxJsxPlugin };

package/dist/index.js

@@ -0,0 +1,541 @@
+/**
+ * markdown-it-mdx-jsx — MDX/JSX component support for markdown-it.
+ *
+ * Dual-context parser following the micromark-extension-mdx-jsx architecture:
+ * - Block rule (flow): handles JSX tags at the start of lines, loops to process
+ *   multiple tags per line, recursively tokenizes inner content
+ * - Inline rule (text): handles JSX tags within prose (self-closing, open, close)
+ *
+ * Components are identified by uppercase first letter (React convention).
+ * Emits `jsx_open`, `jsx_close`, `jsx_self_closing` tokens at block level,
+ * and `jsx_inline_open`, `jsx_inline_close`, `jsx_inline_self_closing` at inline level.
+ */
+// ── Attribute parsing ──────────────────────────────────────
+/**
+ * Parse JSX-style attributes from a string.
+ * Handles: key="value", key='value', key={expr}, key={{obj}}, bare key.
+ * Uses brace-depth tracking for JSX expressions.
+ */
+export function parseJsxAttrs(str) {
+    const attrs = {};
+    let i = 0;
+    const len = str.length;
+    while (i < len) {
+        while (i < len && /\s/.test(str[i]))
+            i++;
+        if (i >= len)
+            break;
+        const keyStart = i;
+        while (i < len && /[\w\-.:]/.test(str[i]))
+            i++;
+        const key = str.slice(keyStart, i);
+        if (!key) {
+            i++;
+            continue;
+        }
+        while (i < len && /\s/.test(str[i]))
+            i++;
+        if (i >= len || str[i] !== "=") {
+            attrs[key] = "true";
+            continue;
+        }
+        i++; // skip =
+        while (i < len && /\s/.test(str[i]))
+            i++;
+        if (i >= len) {
+            attrs[key] = "";
+            continue;
+        }
+        const ch = str[i];
+        if (ch === '"' || ch === "'") {
+            const quote = ch;
+            i++;
+            const valStart = i;
+            while (i < len && str[i] !== quote) {
+                if (str[i] === "\\")
+                    i++;
+                i++;
+            }
+            attrs[key] = str.slice(valStart, i);
+            if (i < len)
+                i++;
+        }
+        else if (ch === "{") {
+            const valStart = i;
+            let depth = 0;
+            while (i < len) {
+                if (str[i] === "{")
+                    depth++;
+                else if (str[i] === "}") {
+                    depth--;
+                    if (depth === 0) {
+                        i++;
+                        break;
+                    }
+                }
+                else if (str[i] === '"' || str[i] === "'") {
+                    const q = str[i];
+                    i++;
+                    while (i < len && str[i] !== q) {
+                        if (str[i] === "\\")
+                            i++;
+                        i++;
+                    }
+                }
+                i++;
+            }
+            attrs[key] = str.slice(valStart, i);
+        }
+        else {
+            const valStart = i;
+            while (i < len && !/\s/.test(str[i]) && str[i] !== ">" && str[i] !== "/")
+                i++;
+            attrs[key] = str.slice(valStart, i);
+        }
+    }
+    return attrs;
+}
+/**
+ * Parse a single JSX tag from a string starting at position `pos`.
+ * Returns null if no valid JSX tag found.
+ * Handles multi-line by accepting the full remaining source.
+ */
+function parseTag(src, pos) {
+    if (src.charCodeAt(pos) !== 0x3c /* < */)
+        return null;
+    let i = pos + 1;
+    const len = src.length;
+    // Skip whitespace after <
+    while (i < len && /\s/.test(src[i]))
+        i++;
+    // Check for closing tag: </Tag>
+    const isClose = src[i] === "/";
+    if (isClose)
+        i++;
+    // Must start with uppercase letter (JSX convention)
+    if (i >= len || !/[A-Z]/.test(src[i]))
+        return null;
+    // Read tag name
+    const nameStart = i;
+    while (i < len && /[\w.]/.test(src[i]))
+        i++;
+    const tag = src.slice(nameStart, i);
+    if (isClose) {
+        // Closing tag: skip whitespace, expect >
+        while (i < len && /\s/.test(src[i]))
+            i++;
+        if (i < len && src[i] === ">") {
+            return { tag, attrs: {}, selfClosing: false, isClose: true, length: i - pos + 1 };
+        }
+        return null;
+    }
+    // Opening tag — parse attributes until > or />
+    // Track brace depth for JSX expression attributes
+    let braceDepth = 0;
+    let inQuote = null;
+    const attrStart = i;
+    while (i < len) {
+        const ch = src[i];
+        if (inQuote) {
+            if (ch === "\\") {
+                i += 2;
+                continue;
+            }
+            if (ch === inQuote)
+                inQuote = null;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            i++;
+            continue;
+        }
+        if (ch === "{") {
+            braceDepth++;
+            i++;
+            continue;
+        }
+        if (ch === "}") {
+            braceDepth--;
+            i++;
+            continue;
+        }
+        // Only check for tag end when not inside braces or quotes
+        if (braceDepth === 0) {
+            if (ch === "/" && i + 1 < len && src[i + 1] === ">") {
+                const attrsStr = src.slice(attrStart, i).trim();
+                return {
+                    tag,
+                    attrs: parseJsxAttrs(attrsStr),
+                    selfClosing: true,
+                    isClose: false,
+                    length: i - pos + 2,
+                };
+            }
+            if (ch === ">") {
+                const attrsStr = src.slice(attrStart, i).trim();
+                return {
+                    tag,
+                    attrs: parseJsxAttrs(attrsStr),
+                    selfClosing: false,
+                    isClose: false,
+                    length: i - pos + 1,
+                };
+            }
+        }
+        i++;
+    }
+    return null; // Never found closing >
+}
+// ── Block rule helpers ─────────────────────────────────────
+function getLine(state, line) {
+    const pos = state.bMarks[line] + state.tShift[line];
+    const max = state.eMarks[line];
+    return state.src.slice(pos, max);
+}
+/**
+ * Find the matching closing tag, tracking nesting depth.
+ * Skips fenced code blocks.
+ */
+function findCloseTag(state, startLine, endLine, tag) {
+    let depth = 1;
+    let inFence = false;
+    let fenceChar = "";
+    let fenceLen = 0;
+    for (let line = startLine; line < endLine; line++) {
+        const text = getLine(state, line);
+        const trimmed = text.trim();
+        if (!inFence) {
+            const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+            if (fenceMatch) {
+                inFence = true;
+                fenceChar = fenceMatch[1][0];
+                fenceLen = fenceMatch[1].length;
+                continue;
+            }
+        }
+        else {
+            const re = new RegExp(`^${fenceChar === "~" ? "~" : "\`"}{${fenceLen},}\\s*$`);
+            if (re.test(trimmed))
+                inFence = false;
+            continue;
+        }
+        // Scan the line for opening/closing tags of the same name
+        // This handles multiple tags per line (e.g., </TabItem> <TabItem>)
+        let pos = 0;
+        while (pos < trimmed.length) {
+            const idx = trimmed.indexOf("<", pos);
+            if (idx === -1)
+                break;
+            const parsed = parseTag(trimmed, idx);
+            if (parsed && parsed.tag === tag) {
+                if (parsed.isClose) {
+                    depth--;
+                    if (depth === 0)
+                        return line;
+                }
+                else if (!parsed.selfClosing) {
+                    depth++;
+                }
+                pos = idx + parsed.length;
+            }
+            else {
+                pos = idx + 1;
+            }
+        }
+    }
+    return endLine;
+}
+// ── Block-level tag parsing (handles multi-line tags) ──────
+/**
+ * Parse a JSX tag from block state, starting at `startLine`.
+ * Concatenates lines as needed for multi-line tags.
+ * Returns null if no valid tag found.
+ */
+function parseBlockTag(state, startLine, endLine, offset = 0) {
+    const linePos = state.bMarks[startLine] + state.tShift[startLine];
+    const lineEnd = state.eMarks[startLine];
+    const firstLineText = state.src.slice(linePos, lineEnd);
+    // Try parsing on the current line first
+    const single = parseTag(firstLineText, offset);
+    if (single) {
+        return { ...single, endLine: startLine };
+    }
+    // Check if this looks like the start of a multi-line tag
+    const remaining = firstLineText.slice(offset);
+    const tagStart = remaining.match(/^<\/?([A-Z]\w*)/);
+    if (!tagStart)
+        return null;
+    // Concatenate lines until we find > or />
+    let combined = remaining;
+    let currentLine = startLine + 1;
+    while (currentLine < endLine) {
+        const nextLine = getLine(state, currentLine);
+        combined += "\n" + nextLine;
+        const parsed = parseTag(combined, 0);
+        if (parsed) {
+            return { ...parsed, endLine: currentLine };
+        }
+        currentLine++;
+    }
+    return null;
+}
+// ── Block rule ─────────────────────────────────────────────
+function createJsxBlockRule(options) {
+    const componentSet = options.components ? new Set(options.components) : null;
+    const selfClosingSet = new Set(options.selfClosing || []);
+    return function jsxBlock(state, startLine, endLine, silent) {
+        const pos = state.bMarks[startLine] + state.tShift[startLine];
+        if (state.src.charCodeAt(pos) !== 0x3c /* < */)
+            return false;
+        // Note: we intentionally do NOT check for 4-space code block indent.
+        // Standard markdown treats 4+ indent as code, but JSX components
+        // should be recognized at any indent level — they're explicit tags,
+        // not accidental indentation. This is critical for components nested
+        // inside other components where inner content is heavily indented.
+        // Try to parse a tag (may span multiple lines)
+        const parsed = parseBlockTag(state, startLine, endLine);
+        if (!parsed)
+            return false;
+        if (componentSet && !componentSet.has(parsed.tag))
+            return false;
+        if (silent)
+            return true;
+        const lineEnd = state.eMarks[startLine];
+        const lineText = state.src.slice(pos, lineEnd);
+        // Process this tag and any subsequent tags on the same line
+        return processFlowTags(state, startLine, endLine, pos, lineText, componentSet, selfClosingSet);
+    };
+}
+/**
+ * Process JSX tag(s) starting at `startLine`.
+ *
+ * Handles:
+ * - Single tags on a line
+ * - Multi-line tags (e.g., <Render\n  file="..."\n/>)
+ * - Multiple tags per line (e.g., <Tabs> <TabItem>, </TabItem> <TabItem>)
+ * - Container tags with inner content on the same line as the opening tag
+ *
+ * Following micromark's flow tag approach: after processing one tag,
+ * if there's another `<` on the same line, loop to process it.
+ */
+function processFlowTags(state, startLine, endLine, linePos, lineText, componentSet, selfClosingSet) {
+    // Parse the first tag (may span multiple lines)
+    const parsed = parseBlockTag(state, startLine, endLine, 0);
+    if (!parsed)
+        return false;
+    if (componentSet && !componentSet.has(parsed.tag))
+        return false;
+    const isSelfClosing = parsed.selfClosing || selfClosingSet.has(parsed.tag);
+    // ── Closing tag ──────────────────────────────────────
+    if (parsed.isClose) {
+        const token = state.push("jsx_close", parsed.tag, -1);
+        token.map = [startLine, startLine + 1];
+        state.line = startLine + 1;
+        return true;
+    }
+    // ── Self-closing tag ─────────────────────────────────
+    if (isSelfClosing) {
+        const token = state.push("jsx_self_closing", parsed.tag, 0);
+        token.meta = { attrs: parsed.attrs };
+        token.map = [startLine, parsed.endLine + 1];
+        state.line = parsed.endLine + 1;
+        return true;
+    }
+    // ── Container tag ────────────────────────────────────
+    // Check for single-line container: <Tag>content</Tag> on one line
+    const closeOnSameLine = lineText.indexOf(`</${parsed.tag}>`, parsed.length);
+    if (closeOnSameLine > 0) {
+        const innerText = lineText.slice(parsed.length, closeOnSameLine).trim();
+        const openToken = state.push("jsx_open", parsed.tag, 1);
+        openToken.meta = { attrs: parsed.attrs };
+        openToken.map = [startLine, startLine + 1];
+        if (innerText) {
+            // Emit inline content as a paragraph
+            const pOpen = state.push("paragraph_open", "p", 1);
+            pOpen.map = [startLine, startLine + 1];
+            const inline = state.push("inline", "", 0);
+            inline.content = innerText;
+            inline.map = [startLine, startLine + 1];
+            inline.children = [];
+            state.push("paragraph_close", "p", -1);
+        }
+        const closeToken = state.push("jsx_close", parsed.tag, -1);
+        closeToken.markup = `</${parsed.tag}>`;
+        state.line = startLine + 1;
+        return true;
+    }
+    // Multi-line container — inner content starts on the next line
+    const innerStart = parsed.endLine + 1;
+    const closeLine = findCloseTag(state, innerStart, endLine, parsed.tag);
+    // Emit open token
+    const openToken = state.push("jsx_open", parsed.tag, 1);
+    openToken.meta = { attrs: parsed.attrs };
+    openToken.map = [startLine, closeLine + 1];
+    openToken.markup = `<${parsed.tag}>`;
+    // Adjust blkIndent for indented inner content
+    const oldParentType = state.parentType;
+    const oldLineMax = state.lineMax;
+    const oldBlkIndent = state.blkIndent;
+    let minIndent = Infinity;
+    for (let ln = innerStart; ln < closeLine; ln++) {
+        const lineLen = state.eMarks[ln] - state.bMarks[ln];
+        if (lineLen === 0)
+            continue;
+        const indent = state.sCount[ln];
+        if (indent < minIndent)
+            minIndent = indent;
+    }
+    if (minIndent === Infinity)
+        minIndent = 0;
+    state.parentType = "jsx";
+    state.lineMax = closeLine;
+    if (minIndent > oldBlkIndent)
+        state.blkIndent = minIndent;
+    // Tokenize inner content
+    state.md.block.tokenize(state, innerStart, closeLine);
+    // Restore state
+    state.parentType = oldParentType;
+    state.lineMax = oldLineMax;
+    state.blkIndent = oldBlkIndent;
+    // Emit close token
+    const closeToken = state.push("jsx_close", parsed.tag, -1);
+    closeToken.markup = `</${parsed.tag}>`;
+    state.line = closeLine < endLine ? closeLine + 1 : endLine;
+    return true;
+}
+// ── Inline rule ────────────────────────────────────────────
+function createJsxInlineRule(options) {
+    const componentSet = options.components ? new Set(options.components) : null;
+    const selfClosingSet = new Set(options.selfClosing || []);
+    return function jsxInline(state, silent) {
+        const pos = state.pos;
+        if (state.src.charCodeAt(pos) !== 0x3c /* < */)
+            return false;
+        const parsed = parseTag(state.src, pos);
+        if (!parsed)
+            return false;
+        if (componentSet && !componentSet.has(parsed.tag))
+            return false;
+        if (silent)
+            return true;
+        const isSelfClosing = parsed.selfClosing || selfClosingSet.has(parsed.tag);
+        if (parsed.isClose) {
+            const token = state.push("jsx_inline_close", parsed.tag, -1);
+            token.markup = `</${parsed.tag}>`;
+        }
+        else if (isSelfClosing) {
+            const token = state.push("jsx_inline_self_closing", parsed.tag, 0);
+            token.meta = { attrs: parsed.attrs };
+        }
+        else {
+            const token = state.push("jsx_inline_open", parsed.tag, 1);
+            token.meta = { attrs: parsed.attrs };
+            token.markup = `<${parsed.tag}>`;
+        }
+        state.pos += parsed.length;
+        return true;
+    };
+}
+// ── JSX comment stripping (block rule) ─────────────────────
+function createJsxCommentRule() {
+    return function jsxComment(state, startLine, endLine, silent) {
+        const pos = state.bMarks[startLine] + state.tShift[startLine];
+        const max = state.eMarks[startLine];
+        const text = state.src.slice(pos, max).trim();
+        if (text.match(/^\{\/\*.*\*\/\}\s*$/)) {
+            if (silent)
+                return true;
+            state.line = startLine + 1;
+            return true;
+        }
+        if (text.match(/^\{\/\*/)) {
+            if (silent)
+                return true;
+            let line = startLine;
+            while (line < endLine) {
+                const lineText = getLine(state, line).trim();
+                if (lineText.match(/\*\/\}\s*$/)) {
+                    state.line = line + 1;
+                    return true;
+                }
+                line++;
+            }
+            state.line = endLine;
+            return true;
+        }
+        return false;
+    };
+}
+// ── Import stripping (block rule) ──────────────────────────
+function createImportStripRule() {
+    return function importStrip(state, startLine, endLine, silent) {
+        const pos = state.bMarks[startLine] + state.tShift[startLine];
+        const max = state.eMarks[startLine];
+        const text = state.src.slice(pos, max);
+        if (text.match(/^import\s+.*from\s+["'][^"']*["']\s*;?\s*$/)) {
+            if (silent)
+                return true;
+            state.line = startLine + 1;
+            return true;
+        }
+        if (text.match(/^import\s*\{/)) {
+            if (silent)
+                return true;
+            let line = startLine;
+            while (line < endLine) {
+                const lineText = getLine(state, line);
+                if (lineText.match(/from\s+["'][^"']*["']\s*;?\s*$/)) {
+                    state.line = line + 1;
+                    return true;
+                }
+                line++;
+            }
+            state.line = startLine + 1;
+            return true;
+        }
+        return false;
+    };
+}
+// ── Source normalization ────────────────────────────────────
+/**
+ * Normalize JSX source for line-based parsing.
+ *
+ * markdown-it processes blocks line-by-line. JSX patterns with multiple
+ * tags on one line (common in Cloudflare/Starlight source) need to be
+ * split so each tag starts on its own line.
+ *
+ * Patterns handled:
+ * - `</TabItem> <TabItem>` → two lines
+ * - `<Tabs> <TabItem>` → two lines
+ * - `</TabItem> </Tabs>` → two lines
+ *
+ * Exported so consumers can call it before md.parse() if needed.
+ */
+export function normalizeJsxLines(source) {
+    // Split close tag + open/close tag: </X> <Y or </X> </Y
+    let result = source.replace(/(<\/[A-Z]\w*\s*>)([ \t]+)(<\/?[A-Z])/g, "$1\n$3");
+    // Split open tag end + next tag: ...> <Y (for <Tabs> <TabItem> pattern)
+    result = result.replace(/(>)([ \t]+)(<\/?[A-Z]\w*[\s>])/g, "$1\n$3");
+    return result;
+}
+// ── Plugin entry point ─────────────────────────────────────
+export default function mdxJsxPlugin(md, options = {}) {
+    // Block rules — before code rule to catch JSX tags before they're
+    // treated as indented code blocks (4+ spaces). This is critical for
+    // components nested inside other components where inner content is
+    // heavily indented (e.g. <Steps> inside <TabItem> inside <Tabs>).
+    md.block.ruler.before("code", "jsx_import", createImportStripRule(), {
+        alt: ["paragraph", "reference", "blockquote", "list"],
+    });
+    md.block.ruler.before("code", "jsx_comment", createJsxCommentRule(), {
+        alt: ["paragraph", "reference", "blockquote", "list"],
+    });
+    md.block.ruler.before("code", "jsx_block", createJsxBlockRule(options), {
+        alt: ["paragraph", "reference", "blockquote", "list"],
+    });
+    // Inline rule — before html_inline to catch JSX tags in prose
+    md.inline.ruler.before("html_inline", "jsx_inline", createJsxInlineRule(options));
+}
+export { mdxJsxPlugin };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dogsbay/markdown-it-mdx-jsx",
+  "version": "0.2.0-beta.0",
+  "description": "markdown-it plugin that tokenizes JSX-style component tags inside Markdown — used by @dogsbay/format-starlight",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "markdown-it": "^14.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/markdown-it": "^14.1.2",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/markdown-it-mdx-jsx"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/markdown-it-mdx-jsx",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}