@readme/markdown 12.1.0 → 12.2.0

package/dist/lib/stripComments.d.ts

@@ -1,8 +1,9 @@
 interface Opts {
     mdx?: boolean;
+    mdxish?: boolean;
 }
 /**
  * Removes Markdown and MDX comments.
  */
-declare function stripComments(doc: string, { mdx }?: Opts): Promise<string>;
+declare function stripComments(doc: string, { mdx, mdxish }?: Opts): Promise<string>;
 export default stripComments;

package/dist/main.js

@@ -52923,6 +52923,37 @@ const stripCommentsTransformer = () => {
 
 
 const STRIP_TAGS = ['script', 'style'];
+/**
+ * Extract variable key from MDX expression AST (e.g., {user.name} → 'name')
+ * Uses ESTree AST inspection, matching the approach in processor/transform/variables.ts
+ *
+ * @see https://github.com/syntax-tree/mdast-util-mdx-expression - MdxTextExpressionHast type
+ * @see https://github.com/estree/estree/blob/master/es5.md - ESTree spec for expression types
+ */
+function extractMdxVariableKey(node) {
+    const estree = node.data?.estree;
+    if (!estree || estree.type !== 'Program' || estree.body.length === 0)
+        return undefined;
+    const statement = estree.body[0];
+    if (statement.type !== 'ExpressionStatement')
+        return undefined;
+    const expr = statement.expression;
+    if (expr.type !== 'MemberExpression')
+        return undefined;
+    const memberExpr = expr;
+    const obj = memberExpr.object;
+    if (obj.type !== 'Identifier' || obj.name !== 'user')
+        return undefined;
+    const prop = memberExpr.property;
+    if (prop.type === 'Identifier') {
+        return prop.name;
+    }
+    if (prop.type === 'Literal') {
+        const val = prop.value;
+        return typeof val === 'string' ? val : undefined;
+    }
+    return undefined;
+}
 function plain_one(node, opts) {
     if (node.type === 'comment')
         return '';
@@ -52946,6 +52977,8 @@ function plain_one(node, opts) {
                 const body = children ? plain_all({ type: 'root', children }, opts) : '';
                 return [icon, ' ', title, title && body && ': ', body].filter(Boolean).join('');
             }
+            // 'variable' (lowercase) comes from mdxish() after rehypeRaw normalizes HTML tag names
+            case 'variable':
             case 'Variable': {
                 const key = node.properties.name.toString();
                 const val = 'variables' in opts && opts.variables[key];
@@ -52967,6 +53000,13 @@ function plain_one(node, opts) {
                 break;
         }
     }
+    // Handle MDX expressions like {user.name}
+    if (node.type === 'mdxTextExpression') {
+        const key = extractMdxVariableKey(node);
+        if (key) {
+            return ('variables' in opts && opts.variables[key]) || key;
+        }
+    }
     if ('value' in node) {
         return node.value;
     }
@@ -86628,11 +86668,27 @@ const getDepth = (el) => {
         return Infinity;
     return parseInt(el.tagName?.match(/^h(\d)/)[1], 10);
 };
+/**
+ * Flatten Variables into a simple key-value map for static resolution.
+ * Merges user values with defaults (user values take precedence).
+ */
+const flattenVariables = (variables) => {
+    if (!variables)
+        return {};
+    return {
+        ...variables.user,
+        ...Object.fromEntries((variables.defaults || []).filter(d => !(d.name in variables.user)).map(d => [d.name, d.default])),
+    };
+};
 /*
  * `tocToHast` consumes the list generated by `rehypeToc` and produces a hast
  * of nested lists to be rendered as a table of contents.
+ *
+ * @param headings - The list of heading elements to render
+ * @param variables - Optional user variables for resolving Variable nodes in headings
  */
-const tocToHast = (headings = []) => {
+const tocToHast = (headings = [], variables) => {
+    const flatVars = flattenVariables(variables);
     const headingDepths = headings.map(getDepth);
     const min = Math.min(...headingDepths);
     const ast = hastscript_lib_h('ul');
@@ -86650,7 +86706,7 @@ const tocToHast = (headings = []) => {
             stack.pop();
         }
         if (heading.properties) {
-            const content = lib_plain({ type: 'root', children: heading.children });
+            const content = lib_plain({ type: 'root', children: heading.children }, { variables: flatVars });
             stack[stack.length - 1].children.push(hastscript_lib_h('li', null, hastscript_lib_h('a', { href: `#${heading.properties.id}` }, content)));
         }
     });
@@ -86660,8 +86716,12 @@ const tocToHast = (headings = []) => {
  * `tocHastToMdx` is a utility for combining `TocList`s of a root document and
  * any child components it may have. Once combined it will generate a markdown
  * doc representing a table of contents.
+ *
+ * @param toc - The list of TOC elements
+ * @param components - Custom components that may contain headings
+ * @param variables - Optional user variables for resolving Variable nodes in headings
  */
-const tocHastToMdx = (toc, components) => {
+const tocHastToMdx = (toc, components, variables) => {
     if (typeof toc === 'undefined')
         return '';
     const injected = toc.flatMap(node => {
@@ -86670,7 +86730,7 @@ const tocHastToMdx = (toc, components) => {
         }
         return node;
     });
-    const tocHast = tocToHast(injected);
+    const tocHast = tocToHast(injected, variables);
     return lib_mdx({ type: 'root', children: [tocHast] }, { hast: true });
 };
 
@@ -93529,6 +93589,61 @@ function restoreCodeBlocks(content, protectedCode) {
         return protectedCode.codeBlocks[parseInt(idx, 10)];
     });
 }
+/**
+ * Escapes unbalanced braces in content to prevent MDX expression parsing errors.
+ * Handles: already-escaped braces, string literals inside expressions, nested balanced braces.
+ */
+function escapeUnbalancedBraces(content) {
+    const opens = [];
+    const unbalanced = new Set();
+    let strDelim = null;
+    let strEscaped = false;
+    for (let i = 0; i < content.length; i += 1) {
+        const ch = content[i];
+        // Track strings inside expressions to ignore braces within them
+        if (opens.length > 0) {
+            if (strDelim) {
+                if (strEscaped)
+                    strEscaped = false;
+                else if (ch === '\\')
+                    strEscaped = true;
+                else if (ch === strDelim)
+                    strDelim = null;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                strDelim = ch;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+        }
+        // Skip already-escaped braces (count preceding backslashes)
+        if (ch === '{' || ch === '}') {
+            let bs = 0;
+            for (let j = i - 1; j >= 0 && content[j] === '\\'; j -= 1)
+                bs += 1;
+            if (bs % 2 === 1) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+        }
+        if (ch === '{')
+            opens.push(i);
+        else if (ch === '}') {
+            if (opens.length > 0)
+                opens.pop();
+            else
+                unbalanced.add(i);
+        }
+    }
+    opens.forEach(pos => unbalanced.add(pos));
+    if (unbalanced.size === 0)
+        return content;
+    return Array.from(content)
+        .map((ch, i) => (unbalanced.has(i) ? `\\${ch}` : ch))
+        .join('');
+}
 /**
  * Converts JSX attribute expressions (attribute={expression}) to HTML attributes (attribute="value").
  * Handles style objects (camelCase → kebab-case), className → class, and JSON stringifies objects.
@@ -93645,7 +93760,9 @@ function preprocessJSXExpressions(content, context = {}) {
     // For inline expressions, we use a library to parse the expression & evaluate it later
     // For attribute expressions, it was difficult to use a library to parse them, so do it manually
     processed = evaluateAttributeExpressions(processed, context, protectedCode);
-    // Step 4: Restore protected code blocks
+    // Step 4: Escape unbalanced braces to prevent MDX expression parsing errors
+    processed = escapeUnbalancedBraces(processed);
+    // Step 5: Restore protected code blocks
     processed = restoreProtectedCodes(processed, protectedCode);
     return processed;
 }
@@ -95440,7 +95557,7 @@ function buildRMDXModule(content, headings, tocHast, opts) {
  * @see {@link https://github.com/readmeio/rmdx/blob/main/docs/mdxish-flow.md}
  */
 const renderMdxish = (tree, opts = {}) => {
-    const { components: userComponents = {}, ...contextOpts } = opts;
+    const { components: userComponents = {}, variables, ...contextOpts } = opts;
     const components = {
         ...loadComponents(),
         ...userComponents,
@@ -95449,8 +95566,8 @@ const renderMdxish = (tree, opts = {}) => {
     const componentsForRehype = exportComponentsForRehype(components);
     const processor = createRehypeReactProcessor(componentsForRehype);
     const content = processor.stringify(tree);
-    const tocHast = headings.length > 0 ? tocToHast(headings) : null;
-    return buildRMDXModule(content, headings, tocHast, contextOpts);
+    const tocHast = headings.length > 0 ? tocToHast(headings, variables) : null;
+    return buildRMDXModule(content, headings, tocHast, { ...contextOpts, variables });
 };
 /* harmony default export */ const lib_renderMdxish = (renderMdxish);
 
@@ -95560,7 +95677,7 @@ const run_run = (string, _opts = {}) => {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { Toc: _Toc, toc, default: Content, stylesheet, ...exports } = exec(string);
     let Toc;
-    const tocMdx = tocHastToMdx(toc, tocsByTag);
+    const tocMdx = tocHastToMdx(toc, tocsByTag, variables);
     if (tocMdx) {
         const compiledToc = lib_compile(tocMdx);
         const tocModule = exec(compiledToc, { useMDXComponents: () => ({ p: Fragment }) });
@@ -95621,13 +95738,26 @@ const mdxishTags_tags = (doc) => {
 
 
 
+
+
+
 /**
  * Removes Markdown and MDX comments.
  */
-async function stripComments(doc, { mdx } = {}) {
+async function stripComments(doc, { mdx, mdxish } = {}) {
     const { replaced, blocks } = extractMagicBlocks(doc);
-    const processor = unified()
+    const processor = unified();
+    // we still require these two extensions because:
+    // 1. we can rely on remarkMdx to parse MDXish
+    // 2. we need to parse JSX comments into mdxTextExpression nodes so that the transformers can pick them up
+    if (mdxish) {
+        processor
+            .data('micromarkExtensions', [mdxExpression({ allowEmpty: true })])
+            .data('fromMarkdownExtensions', [mdxExpressionFromMarkdown()]);
+    }
+    processor
         .use(remarkParse)
+        .use(normalize_malformed_md_syntax)
         .use(mdx ? remarkMdx : undefined)
         .use(stripCommentsTransformer)
         .use(remarkStringify, mdx
@@ -95647,8 +95777,14 @@ async function stripComments(doc, { mdx } = {}) {
                 // Preserve tight sibling code blocks without adding extra newlines between them.
                 // Our markdown renderer uses this to group these code blocks into a tabbed interface.
                 (left, right) => {
-                    // 0 = no newline between blocks
-                    return left.type === 'code' && right.type === 'code' ? 0 : undefined;
+                    if (left.type === 'code' && right.type === 'code') {
+                        const isTight = left.position &&
+                            right.position &&
+                            right.position.start.line - left.position.end.line === 1; // Are the blocks on adjacent lines?
+                        // 0 = no newline between blocks
+                        return isTight ? 0 : undefined;
+                    }
+                    return undefined;
                 },
             ],
         });

package/dist/main.node.js

@@ -73127,6 +73127,37 @@ const stripCommentsTransformer = () => {
 
 
 const STRIP_TAGS = ['script', 'style'];
+/**
+ * Extract variable key from MDX expression AST (e.g., {user.name} → 'name')
+ * Uses ESTree AST inspection, matching the approach in processor/transform/variables.ts
+ *
+ * @see https://github.com/syntax-tree/mdast-util-mdx-expression - MdxTextExpressionHast type
+ * @see https://github.com/estree/estree/blob/master/es5.md - ESTree spec for expression types
+ */
+function extractMdxVariableKey(node) {
+    const estree = node.data?.estree;
+    if (!estree || estree.type !== 'Program' || estree.body.length === 0)
+        return undefined;
+    const statement = estree.body[0];
+    if (statement.type !== 'ExpressionStatement')
+        return undefined;
+    const expr = statement.expression;
+    if (expr.type !== 'MemberExpression')
+        return undefined;
+    const memberExpr = expr;
+    const obj = memberExpr.object;
+    if (obj.type !== 'Identifier' || obj.name !== 'user')
+        return undefined;
+    const prop = memberExpr.property;
+    if (prop.type === 'Identifier') {
+        return prop.name;
+    }
+    if (prop.type === 'Literal') {
+        const val = prop.value;
+        return typeof val === 'string' ? val : undefined;
+    }
+    return undefined;
+}
 function plain_one(node, opts) {
     if (node.type === 'comment')
         return '';
@@ -73150,6 +73181,8 @@ function plain_one(node, opts) {
                 const body = children ? plain_all({ type: 'root', children }, opts) : '';
                 return [icon, ' ', title, title && body && ': ', body].filter(Boolean).join('');
             }
+            // 'variable' (lowercase) comes from mdxish() after rehypeRaw normalizes HTML tag names
+            case 'variable':
             case 'Variable': {
                 const key = node.properties.name.toString();
                 const val = 'variables' in opts && opts.variables[key];
@@ -73171,6 +73204,13 @@ function plain_one(node, opts) {
                 break;
         }
     }
+    // Handle MDX expressions like {user.name}
+    if (node.type === 'mdxTextExpression') {
+        const key = extractMdxVariableKey(node);
+        if (key) {
+            return ('variables' in opts && opts.variables[key]) || key;
+        }
+    }
     if ('value' in node) {
         return node.value;
     }
@@ -106832,11 +106872,27 @@ const getDepth = (el) => {
         return Infinity;
     return parseInt(el.tagName?.match(/^h(\d)/)[1], 10);
 };
+/**
+ * Flatten Variables into a simple key-value map for static resolution.
+ * Merges user values with defaults (user values take precedence).
+ */
+const flattenVariables = (variables) => {
+    if (!variables)
+        return {};
+    return {
+        ...variables.user,
+        ...Object.fromEntries((variables.defaults || []).filter(d => !(d.name in variables.user)).map(d => [d.name, d.default])),
+    };
+};
 /*
  * `tocToHast` consumes the list generated by `rehypeToc` and produces a hast
  * of nested lists to be rendered as a table of contents.
+ *
+ * @param headings - The list of heading elements to render
+ * @param variables - Optional user variables for resolving Variable nodes in headings
  */
-const tocToHast = (headings = []) => {
+const tocToHast = (headings = [], variables) => {
+    const flatVars = flattenVariables(variables);
     const headingDepths = headings.map(getDepth);
     const min = Math.min(...headingDepths);
     const ast = hastscript_lib_h('ul');
@@ -106854,7 +106910,7 @@ const tocToHast = (headings = []) => {
             stack.pop();
         }
         if (heading.properties) {
-            const content = lib_plain({ type: 'root', children: heading.children });
+            const content = lib_plain({ type: 'root', children: heading.children }, { variables: flatVars });
             stack[stack.length - 1].children.push(hastscript_lib_h('li', null, hastscript_lib_h('a', { href: `#${heading.properties.id}` }, content)));
         }
     });
@@ -106864,8 +106920,12 @@ const tocToHast = (headings = []) => {
  * `tocHastToMdx` is a utility for combining `TocList`s of a root document and
  * any child components it may have. Once combined it will generate a markdown
  * doc representing a table of contents.
+ *
+ * @param toc - The list of TOC elements
+ * @param components - Custom components that may contain headings
+ * @param variables - Optional user variables for resolving Variable nodes in headings
  */
-const tocHastToMdx = (toc, components) => {
+const tocHastToMdx = (toc, components, variables) => {
     if (typeof toc === 'undefined')
         return '';
     const injected = toc.flatMap(node => {
@@ -106874,7 +106934,7 @@ const tocHastToMdx = (toc, components) => {
         }
         return node;
     });
-    const tocHast = tocToHast(injected);
+    const tocHast = tocToHast(injected, variables);
     return lib_mdx({ type: 'root', children: [tocHast] }, { hast: true });
 };
 
@@ -113733,6 +113793,61 @@ function restoreCodeBlocks(content, protectedCode) {
         return protectedCode.codeBlocks[parseInt(idx, 10)];
     });
 }
+/**
+ * Escapes unbalanced braces in content to prevent MDX expression parsing errors.
+ * Handles: already-escaped braces, string literals inside expressions, nested balanced braces.
+ */
+function escapeUnbalancedBraces(content) {
+    const opens = [];
+    const unbalanced = new Set();
+    let strDelim = null;
+    let strEscaped = false;
+    for (let i = 0; i < content.length; i += 1) {
+        const ch = content[i];
+        // Track strings inside expressions to ignore braces within them
+        if (opens.length > 0) {
+            if (strDelim) {
+                if (strEscaped)
+                    strEscaped = false;
+                else if (ch === '\\')
+                    strEscaped = true;
+                else if (ch === strDelim)
+                    strDelim = null;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                strDelim = ch;
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+        }
+        // Skip already-escaped braces (count preceding backslashes)
+        if (ch === '{' || ch === '}') {
+            let bs = 0;
+            for (let j = i - 1; j >= 0 && content[j] === '\\'; j -= 1)
+                bs += 1;
+            if (bs % 2 === 1) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+        }
+        if (ch === '{')
+            opens.push(i);
+        else if (ch === '}') {
+            if (opens.length > 0)
+                opens.pop();
+            else
+                unbalanced.add(i);
+        }
+    }
+    opens.forEach(pos => unbalanced.add(pos));
+    if (unbalanced.size === 0)
+        return content;
+    return Array.from(content)
+        .map((ch, i) => (unbalanced.has(i) ? `\\${ch}` : ch))
+        .join('');
+}
 /**
  * Converts JSX attribute expressions (attribute={expression}) to HTML attributes (attribute="value").
  * Handles style objects (camelCase → kebab-case), className → class, and JSON stringifies objects.
@@ -113849,7 +113964,9 @@ function preprocessJSXExpressions(content, context = {}) {
     // For inline expressions, we use a library to parse the expression & evaluate it later
     // For attribute expressions, it was difficult to use a library to parse them, so do it manually
     processed = evaluateAttributeExpressions(processed, context, protectedCode);
-    // Step 4: Restore protected code blocks
+    // Step 4: Escape unbalanced braces to prevent MDX expression parsing errors
+    processed = escapeUnbalancedBraces(processed);
+    // Step 5: Restore protected code blocks
     processed = restoreProtectedCodes(processed, protectedCode);
     return processed;
 }
@@ -115644,7 +115761,7 @@ function buildRMDXModule(content, headings, tocHast, opts) {
  * @see {@link https://github.com/readmeio/rmdx/blob/main/docs/mdxish-flow.md}
  */
 const renderMdxish = (tree, opts = {}) => {
-    const { components: userComponents = {}, ...contextOpts } = opts;
+    const { components: userComponents = {}, variables, ...contextOpts } = opts;
     const components = {
         ...loadComponents(),
         ...userComponents,
@@ -115653,8 +115770,8 @@ const renderMdxish = (tree, opts = {}) => {
     const componentsForRehype = exportComponentsForRehype(components);
     const processor = createRehypeReactProcessor(componentsForRehype);
     const content = processor.stringify(tree);
-    const tocHast = headings.length > 0 ? tocToHast(headings) : null;
-    return buildRMDXModule(content, headings, tocHast, contextOpts);
+    const tocHast = headings.length > 0 ? tocToHast(headings, variables) : null;
+    return buildRMDXModule(content, headings, tocHast, { ...contextOpts, variables });
 };
 /* harmony default export */ const lib_renderMdxish = (renderMdxish);
 
@@ -115764,7 +115881,7 @@ const run_run = (string, _opts = {}) => {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { Toc: _Toc, toc, default: Content, stylesheet, ...exports } = exec(string);
     let Toc;
-    const tocMdx = tocHastToMdx(toc, tocsByTag);
+    const tocMdx = tocHastToMdx(toc, tocsByTag, variables);
     if (tocMdx) {
         const compiledToc = lib_compile(tocMdx);
         const tocModule = exec(compiledToc, { useMDXComponents: () => ({ p: Fragment }) });
@@ -115825,13 +115942,26 @@ const mdxishTags_tags = (doc) => {
 
 
 
+
+
+
 /**
  * Removes Markdown and MDX comments.
  */
-async function stripComments(doc, { mdx } = {}) {
+async function stripComments(doc, { mdx, mdxish } = {}) {
     const { replaced, blocks } = extractMagicBlocks(doc);
-    const processor = unified()
+    const processor = unified();
+    // we still require these two extensions because:
+    // 1. we can rely on remarkMdx to parse MDXish
+    // 2. we need to parse JSX comments into mdxTextExpression nodes so that the transformers can pick them up
+    if (mdxish) {
+        processor
+            .data('micromarkExtensions', [mdxExpression({ allowEmpty: true })])
+            .data('fromMarkdownExtensions', [mdxExpressionFromMarkdown()]);
+    }
+    processor
         .use(remarkParse)
+        .use(normalize_malformed_md_syntax)
         .use(mdx ? remarkMdx : undefined)
         .use(stripCommentsTransformer)
         .use(remarkStringify, mdx
@@ -115851,8 +115981,14 @@ async function stripComments(doc, { mdx } = {}) {
                 // Preserve tight sibling code blocks without adding extra newlines between them.
                 // Our markdown renderer uses this to group these code blocks into a tabbed interface.
                 (left, right) => {
-                    // 0 = no newline between blocks
-                    return left.type === 'code' && right.type === 'code' ? 0 : undefined;
+                    if (left.type === 'code' && right.type === 'code') {
+                        const isTight = left.position &&
+                            right.position &&
+                            right.position.start.line - left.position.end.line === 1; // Are the blocks on adjacent lines?
+                        // 0 = no newline between blocks
+                        return isTight ? 0 : undefined;
+                    }
+                    return undefined;
                 },
             ],
         });