@mintlify/common 1.0.1118 → 1.0.1120

package/dist/mdx/plugins/remark/remarkExtractTableOfContents.js

@@ -122,21 +122,61 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
                 });
             }
         });
+        const pushEntry = (entry, level) => {
+            if (level !== undefined && Number(level) <= 2) {
+                hasTopLayer = true;
+                contents.push(entry);
+                return;
+            }
+            // Account if there is no first layer
+            let arrToPushInto = contents;
+            if (hasTopLayer) {
+                const lastTopLevel = contents.at(-1);
+                if (lastTopLevel &&
+                    (lastTopLevel.tabId === undefined || lastTopLevel.tabId === entry.tabId) &&
+                    (lastTopLevel.viewId === undefined || lastTopLevel.viewId === entry.viewId) &&
+                    (lastTopLevel.variationIds === undefined ||
+                        (entry.variationIds !== undefined &&
+                            entry.variationIds.every((id) => { var _a; return (_a = lastTopLevel.variationIds) === null || _a === void 0 ? void 0 : _a.includes(id); })))) {
+                    arrToPushInto = lastTopLevel.children;
+                }
+            }
+            arrToPushInto.push(entry);
+        };
         visit(tree, (node) => {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d, _e, _f, _g;
             if (excludedNodes.has(node))
                 return;
             const currentTabId = tabContentMap.get(node);
             const currentViewId = viewContentMap.get(node);
             const currentVariationIds = variationContentMap.get(node);
+            if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+                const fragmentHeadings = (_a = node.data) === null || _a === void 0 ? void 0 : _a.tableOfContents;
+                if (!(fragmentHeadings === null || fragmentHeadings === void 0 ? void 0 : fragmentHeadings.length))
+                    return;
+                // headings compiled inside an <MDX> fragment (see remarkMdxExpandExpressions); merged in
+                // document order, slugs registered so later page headings do not reuse them
+                const register = (entries) => {
+                    var _a;
+                    for (const entry of entries) {
+                        seenSlugs.set(entry.slug, ((_a = seenSlugs.get(entry.slug)) !== null && _a !== void 0 ? _a : 0) + 1);
+                        register(entry.children);
+                    }
+                };
+                register(fragmentHeadings);
+                for (const heading of fragmentHeadings) {
+                    pushEntry(Object.assign(Object.assign({}, heading), { tabId: currentTabId, viewId: currentViewId, variationIds: currentVariationIds }), heading.depth);
+                }
+                return;
+            }
             const isValidHeading = node.type === 'heading' && HEADING_LEVELS.includes(node.depth);
-            const isValidMdxHeading = node.type === 'mdxJsxFlowElement' && HEADING_NAMES.includes((_a = node.name) !== null && _a !== void 0 ? _a : '');
+            const isValidMdxHeading = node.type === 'mdxJsxFlowElement' && HEADING_NAMES.includes((_b = node.name) !== null && _b !== void 0 ? _b : '');
             const isTransformedHeading = node.type === 'mdxJsxFlowElement' && node.name === 'Heading';
             const isValidUpdate = node.type === 'mdxJsxFlowElement' &&
                 node.name === 'Update' &&
                 node.attributes.some((attr) => 'name' in attr && attr.name === 'label');
             const stepTitleSize = node.type === 'mdxJsxFlowElement' && node.name === 'Step'
-                ? ((_b = getStringAttribute(node.attributes, 'titleSize')) !== null && _b !== void 0 ? _b : inheritedStepTitleSizeMap.get(node))
+                ? ((_c = getStringAttribute(node.attributes, 'titleSize')) !== null && _c !== void 0 ? _c : inheritedStepTitleSizeMap.get(node))
                 : undefined;
             const hasNoAnchor = node.type === 'mdxJsxFlowElement' &&
                 node.attributes.some((attr) => 'name' in attr &&
@@ -145,7 +185,7 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
                         attr.value === 'true' ||
                         (typeof attr.value === 'object' && attr.value.value === 'true')));
             const stepTitle = node.type === 'mdxJsxFlowElement' && node.name === 'Step'
-                ? getTitleMarkdownText(node, (_c = getStringAttribute(node.attributes, 'title')) !== null && _c !== void 0 ? _c : '')
+                ? getTitleMarkdownText(node, (_d = getStringAttribute(node.attributes, 'title')) !== null && _d !== void 0 ? _d : '')
                 : undefined;
             const isValidStep = node.type === 'mdxJsxFlowElement' &&
                 node.name === 'Step' &&
@@ -154,7 +194,7 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
                 (stepTitle === null || stepTitle === void 0 ? void 0 : stepTitle.trim()) !== '';
             const hasIdAttribute = node.type === 'mdxJsxFlowElement' &&
                 node.attributes.some((attr) => 'name' in attr && attr.name === 'id');
-            const isAvoidedPageMode = AVOIDED_PAGE_MODES.includes((_d = pageMetadata === null || pageMetadata === void 0 ? void 0 : pageMetadata.mode) !== null && _d !== void 0 ? _d : '');
+            const isAvoidedPageMode = AVOIDED_PAGE_MODES.includes((_e = pageMetadata === null || pageMetadata === void 0 ? void 0 : pageMetadata.mode) !== null && _e !== void 0 ? _e : '');
             if (!isValidHeading &&
                 !isValidMdxHeading &&
                 !isTransformedHeading &&
@@ -172,7 +212,7 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
             }
             else if ('name' in node && node.name === 'Step') {
                 const titleSizeToLevel = { h2: 2, h3: 3, h4: 4 };
-                level = (_e = titleSizeToLevel[stepTitleSize !== null && stepTitleSize !== void 0 ? stepTitleSize : '']) !== null && _e !== void 0 ? _e : 3;
+                level = (_f = titleSizeToLevel[stepTitleSize !== null && stepTitleSize !== void 0 ? stepTitleSize : '']) !== null && _f !== void 0 ? _f : 3;
                 // @ts-expect-error we're assigning to depth despite the node not containing depth in the type
                 node.depth = level;
             }
@@ -185,7 +225,7 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
                     level = levelAttr.value;
                 }
             }
-            else if ('name' in node && ((_f = node.name) === null || _f === void 0 ? void 0 : _f[1])) {
+            else if ('name' in node && ((_g = node.name) === null || _g === void 0 ? void 0 : _g[1])) {
                 const num = Number(node.name[1]);
                 level = !isNaN(num) ? num : undefined;
                 if (level !== undefined) {
@@ -252,42 +292,15 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
             node.name = node.name === 'Update' ? 'Update' : node.name === 'Step' ? 'Step' : 'Heading';
             // @ts-expect-error we've already written to 'depth' and so this should be safe
             const depth = node.depth;
-            if (level !== undefined && Number(level) <= 2) {
-                hasTopLayer = true;
-                contents.push({
-                    title,
-                    slug,
-                    depth,
-                    children: [],
-                    tabId: currentTabId,
-                    viewId: currentViewId,
-                    variationIds: currentVariationIds,
-                });
-            }
-            else {
-                // Account if there is no first layer
-                let arrToPushInto = contents;
-                if (hasTopLayer) {
-                    const lastTopLevel = contents.at(-1);
-                    if (lastTopLevel &&
-                        (lastTopLevel.tabId === undefined || lastTopLevel.tabId === currentTabId) &&
-                        (lastTopLevel.viewId === undefined || lastTopLevel.viewId === currentViewId) &&
-                        (lastTopLevel.variationIds === undefined ||
-                            (currentVariationIds !== undefined &&
-                                currentVariationIds.every((id) => { var _a; return (_a = lastTopLevel.variationIds) === null || _a === void 0 ? void 0 : _a.includes(id); })))) {
-                        arrToPushInto = lastTopLevel.children;
-                    }
-                }
-                arrToPushInto.push({
-                    title,
-                    slug,
-                    depth,
-                    children: [],
-                    tabId: currentTabId,
-                    viewId: currentViewId,
-                    variationIds: currentVariationIds,
-                });
-            }
+            pushEntry({
+                title,
+                slug,
+                depth,
+                children: [],
+                tabId: currentTabId,
+                viewId: currentViewId,
+                variationIds: currentVariationIds,
+            }, level);
         });
         if (mdxExtracts) {
             mdxExtracts.tableOfContents = contents;

package/dist/mdx/plugins/remark/remarkMdxExpandExpressions.d.ts

@@ -71,9 +71,10 @@ export declare const MAX_MDX_FRAGMENTS_PER_PAGE = 500;
  * `<p>` wrapper is unwrapped so it does not nest in the surrounding paragraph.
  *
  * Escaping: the fragment source is JSX text, so a literal brace must be written the JSX way,
- * e.g. `{'{'}` / `{'}'}`; that expression is then evaluated by MDX and renders the brace. For the
- * same reason a custom heading anchor cannot use `## Title {#id}` inside an expression fragment;
- * write `<h2 id="id">Title</h2>` instead. Nothing beyond dedenting is done to the recovered text.
+ * e.g. `{'{'}` / `{'}'}`; that expression is then evaluated by MDX and renders the brace. A custom
+ * heading anchor (`## Title {#id}`) is fine: `preprocessCustomHeadingIds` rewrites it before the
+ * expression is parsed, at any indent inside `<MDX>`. Nothing beyond dedenting is done to the
+ * recovered text.
  *
  * Components defined on the page (`export const Local = () => …`, and named snippet imports,
  * which prebuild rewrites into page exports) are passed into the fragment pipeline as known
@@ -86,9 +87,11 @@ export declare const MAX_MDX_FRAGMENTS_PER_PAGE = 500;
  * feeds the side panel / sticky examples.
  *
  * Table of contents: the fragment pipeline runs `remarkExtractTableOfContents` (it also rewrites
- * headings to `<Heading>`, so it cannot be skipped) into a fragment-scoped extracts object that is
- * discarded, so headings inside an expression fragment get ids but are not listed in the page's
- * table of contents yet — that merge is a follow-up PR.
+ * headings to `<Heading>`, so it cannot be skipped) into a fragment-scoped extracts object; the
+ * headings are stored on the expression node as `data.tableOfContents` and merged into the page
+ * TOC in document order by the page-level run. Headings of a branch that never renders are still
+ * listed, and a fragment heading that repeats a page heading's title keeps its own id — a
+ * render-time reconcile is the planned follow-up.
  */
 export declare const remarkMdxExpandExpressions: (options: RemarkMdxExpandExpressionsOptions) => (tree: Root) => Promise<void>;
 export declare const dedent: (text: string) => string;

package/dist/mdx/plugins/remark/remarkMdxExpandExpressions.js

@@ -61,9 +61,10 @@ export const MAX_MDX_FRAGMENTS_PER_PAGE = 500;
  * `<p>` wrapper is unwrapped so it does not nest in the surrounding paragraph.
  *
  * Escaping: the fragment source is JSX text, so a literal brace must be written the JSX way,
- * e.g. `{'{'}` / `{'}'}`; that expression is then evaluated by MDX and renders the brace. For the
- * same reason a custom heading anchor cannot use `## Title {#id}` inside an expression fragment;
- * write `<h2 id="id">Title</h2>` instead. Nothing beyond dedenting is done to the recovered text.
+ * e.g. `{'{'}` / `{'}'}`; that expression is then evaluated by MDX and renders the brace. A custom
+ * heading anchor (`## Title {#id}`) is fine: `preprocessCustomHeadingIds` rewrites it before the
+ * expression is parsed, at any indent inside `<MDX>`. Nothing beyond dedenting is done to the
+ * recovered text.
  *
  * Components defined on the page (`export const Local = () => …`, and named snippet imports,
  * which prebuild rewrites into page exports) are passed into the fragment pipeline as known
@@ -76,9 +77,11 @@ export const MAX_MDX_FRAGMENTS_PER_PAGE = 500;
  * feeds the side panel / sticky examples.
  *
  * Table of contents: the fragment pipeline runs `remarkExtractTableOfContents` (it also rewrites
- * headings to `<Heading>`, so it cannot be skipped) into a fragment-scoped extracts object that is
- * discarded, so headings inside an expression fragment get ids but are not listed in the page's
- * table of contents yet — that merge is a follow-up PR.
+ * headings to `<Heading>`, so it cannot be skipped) into a fragment-scoped extracts object; the
+ * headings are stored on the expression node as `data.tableOfContents` and merged into the page
+ * TOC in document order by the page-level run. Headings of a branch that never renders are still
+ * listed, and a fragment heading that repeats a page heading's title keeps its own id — a
+ * render-time reconcile is the planned follow-up.
  */
 export const remarkMdxExpandExpressions = (options) => (tree) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c;
@@ -124,6 +127,7 @@ const expandExpression = (node_1, options_1, _a) => __awaiter(void 0, [node_1, o
     const elements = collectMdxElements(expression);
     if (elements.length === 0)
         return;
+    const headings = [];
     let changed = false;
     for (const element of elements) {
         const opening = element.openingElement;
@@ -172,6 +176,9 @@ const expandExpression = (node_1, options_1, _a) => __awaiter(void 0, [node_1, o
                 ? compiled.children
                 : [compiled];
         changed = true;
+        if (fragmentExtracts.tableOfContents) {
+            headings.push(...fragmentExtracts.tableOfContents);
+        }
     }
     if (!changed)
         return;
@@ -183,6 +190,9 @@ const expandExpression = (node_1, options_1, _a) => __awaiter(void 0, [node_1, o
     };
     node.value = toJs(program, { handlers: jsxHandlers }).value.replace(/;\s*$/, '');
     node.data = Object.assign(Object.assign({}, node.data), { estree: program });
+    if (headings.length > 0) {
+        node.data.tableOfContents = headings;
+    }
 });
 const collectMdxElements = (expression) => {
     const elements = [];

package/dist/mdx/preprocessCustomHeadingIds.d.ts

@@ -16,6 +16,11 @@ export interface PreprocessCustomHeadingIdsOptions {
  *
  * Uses a line-by-line scan with fence state tracking to skip headings inside
  * code blocks, avoiding backtracking over large documents.
+ *
+ * Headings are matched with at most 3 spaces of indent (deeper is an indented code block),
+ * except inside an `<MDX>` block — including one nested in a `{…}` expression, where authors
+ * indent the body — whose content is dedented before parsing, so any indent is accepted there.
+ * Without this the `{#id}` would reach the expression parser as a JSX expression and fail.
  */
 export declare function preprocessCustomHeadingIds(content: string, options?: PreprocessCustomHeadingIdsOptions): string;
 export interface JsxHeadingElement extends MdxJsxFlowElement {

package/dist/mdx/preprocessCustomHeadingIds.js

@@ -1,4 +1,12 @@
 const HEADING_ID_RE = /^( {0,3})(#{1,6})\s+(.+?)\s*\{\s*#([^}]+?)\s*\}\s*$/;
+/**
+ * Inside an `<MDX>` block the body is dedented before it is parsed, so indentation carries no
+ * meaning there (4+ spaces is not an indented code block) and any indent may precede the heading.
+ */
+const MDX_HEADING_ID_RE = /^(\s*)(#{1,6})\s+(.+?)\s*\{\s*#([^}]+?)\s*\}\s*$/;
+// `<MDX>` or `<MDX className="x">`; not `<MDX />` (no body) and not `<MDXProvider>`
+const MDX_OPEN_RE = /<MDX(?:\s[^>]*[^/>\s])?\s*>/g;
+const MDX_CLOSE_RE = /<\/MDX\s*>/g;
 const UNSAFE_HTML_ATTR_CHARS = /[<>"]/g;
 /**
  * Characters to strip from custom heading IDs in the default (non-editor) path.
@@ -23,13 +31,19 @@ function normalizeCustomId(raw) {
  *
  * Uses a line-by-line scan with fence state tracking to skip headings inside
  * code blocks, avoiding backtracking over large documents.
+ *
+ * Headings are matched with at most 3 spaces of indent (deeper is an indented code block),
+ * except inside an `<MDX>` block — including one nested in a `{…}` expression, where authors
+ * indent the body — whose content is dedented before parsing, so any indent is accepted there.
+ * Without this the `{#id}` would reach the expression parser as a JSX expression and fail.
  */
 export function preprocessCustomHeadingIds(content, options) {
-    var _a;
+    var _a, _b, _c, _d, _e;
     const lines = content.split('\n');
     const result = [];
     let fenceChar;
     let fenceCount = 0;
+    let mdxDepth = 0;
     for (const line of lines) {
         const stripped = line.trimStart();
         if (fenceChar !== undefined) {
@@ -46,7 +60,7 @@ export function preprocessCustomHeadingIds(content, options) {
             result.push(line);
             continue;
         }
-        const heading = HEADING_ID_RE.exec(line);
+        const heading = (mdxDepth > 0 ? MDX_HEADING_ID_RE : HEADING_ID_RE).exec(line);
         if ((heading === null || heading === void 0 ? void 0 : heading[2]) && heading[3] && heading[4]) {
             const indent = (_a = heading[1]) !== null && _a !== void 0 ? _a : '';
             const level = heading[2].length;
@@ -56,6 +70,7 @@ export function preprocessCustomHeadingIds(content, options) {
             result.push(`${indent}<h${level} id="${sanitizedId}">`, `${indent}${heading[3]}`, `${indent}</h${level}>`);
             continue;
         }
+        mdxDepth = Math.max(0, mdxDepth + ((_c = (_b = line.match(MDX_OPEN_RE)) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) - ((_e = (_d = line.match(MDX_CLOSE_RE)) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0));
         result.push(line);
     }
     return result.join('\n');

package/dist/mdx/preprocessCustomHeadingIds.test.js

@@ -23,6 +23,40 @@ describe('preprocessCustomHeadingIds', () => {
         const input = '    ## Heading {#custom-id}';
         expect(preprocessCustomHeadingIds(input)).toBe(input);
     });
+    it('converts headings at any indent inside an <MDX> block', () => {
+        const input = `{variant === "fos" ? (
+  <MDX>
+    ### Request a token {#request-token}
+
+    Body
+  </MDX>
+) : null}
+
+    ## Still code {#not-converted}`;
+        const output = preprocessCustomHeadingIds(input);
+        expect(output).toContain('    <h3 id="request-token">\n    Request a token\n    </h3>');
+        // depth is back to 0 after </MDX>: 4-space indent is an indented code block again
+        expect(output).toContain('    ## Still code {#not-converted}');
+    });
+    it('leaves code fences inside an <MDX> block alone', () => {
+        const input = `<MDX>
+    \`\`\`md
+    ## Heading {#custom-id}
+    \`\`\`
+</MDX>`;
+        expect(preprocessCustomHeadingIds(input)).toBe(input);
+    });
+    it('ignores an unrelated MDX-prefixed tag', () => {
+        const input = '<MDXProvider>\n    ## Heading {#custom-id}\n</MDXProvider>';
+        expect(preprocessCustomHeadingIds(input)).toBe(input);
+    });
+    it('does not treat a self-closing <MDX /> as opening a block', () => {
+        // a self-closing tag has no body; the any-indent rule must not stay on for the rest of the file
+        for (const tag of ['<MDX />', '<MDX/>', '<MDX className="x" />']) {
+            const input = `${tag}\n\n    ## Still code {#not-converted}`;
+            expect(preprocessCustomHeadingIds(input)).toBe(input);
+        }
+    });
     it('leaves tab-indented headings alone', () => {
         const input = '\t## Heading {#custom-id}';
         expect(preprocessCustomHeadingIds(input)).toBe(input);