@mintlify/common 1.0.1020 → 1.0.1022

package/dist/mdx/getMDXOptions.js

@@ -1,4 +1,4 @@
-import { rehypeCodeBlocks, rehypeDynamicTailwindCss, rehypeKeyboardSymbols, rehypeListItemText, rehypeMdxExtractEndpoint, rehypeMdxExtractExamples, rehypeParamFieldIds, rehypeRawComponents, rehypeTable, rehypeUnicodeIds, rehypeZoomImages, remarkExtractChangelogFilters, remarkExtractTableOfContents, remarkFileTree, remarkFrames, remarkComponentIds, remarkMdxInjectSnippets, remarkMdxRemoveUnusedVariables, remarkRemoveImports, remarkMdxExtractPanel, remarkResolveRelativeLinks, remarkVideo, remarkMdxClientComponentBoundaries, remarkExtractMultiView, remarkPrompt, remarkUnwrapJsxHeadings, } from './plugins/index.js';
+import { rehypeCodeBlocks, rehypeDynamicTailwindCss, rehypeKeyboardSymbols, rehypeListItemText, rehypeMdxExtractEndpoint, rehypeMdxExtractExamples, rehypeParamFieldIds, rehypeRawComponents, rehypeTable, rehypeUnicodeIds, rehypeZoomImages, remarkExtractChangelogFilters, remarkExtractTableOfContents, remarkFileTree, remarkFrames, remarkComponentIds, remarkMdxInjectSnippets, remarkMdxRemoveUnusedVariables, remarkRemoveImports, remarkMdxExtractPanel, remarkResolveRelativeLinks, remarkVideo, remarkMdxClientComponentBoundaries, remarkExtractMultiView, remarkPrompt, remarkUnwrapInlineJsx, remarkUnwrapJsxHeadings, } from './plugins/index.js';
 import { remarkMdxRemoveUnknownJsx } from './plugins/remark/remarkMdxRemoveUnknownJsx/index.js';
 import { remarkMermaid } from './plugins/remark/remarkMermaid.js';
 // avoid running extractors unnecessarily
@@ -18,6 +18,7 @@ export const getMDXOptions = ({ data, remarkPlugins = [], rehypePlugins = [], md
             remarkPrompt,
             [remarkComponentIds, data.pageMetadata],
             remarkUnwrapJsxHeadings,
+            remarkUnwrapInlineJsx,
             [remarkExtractTableOfContents, mdxExtracts, data.pageMetadata], // modifies tree so cannot be excluded
             [remarkExtractChangelogFilters, mdxExtracts],
             [remarkMdxExtractPanel, mdxExtracts],

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

@@ -15,10 +15,12 @@ export * from './remarkSplitTabs.js';
 export * from './remarkComponentIds.js';
 export * from './remarkMdxExtractPanel.js';
 export * from './remarkValidateSteps.js';
+export * from './remarkValidateVisibility.js';
 export * from './remarkValidateTabs.js';
 export * from './remarkVideo.js';
 export * from './remarkExtractMultiView.js';
 export * from './remarkPrompt.js';
 export * from './remarkResolveRelativeLinks.js';
+export * from './remarkUnwrapInlineJsx.js';
 export * from './remarkUnwrapJsxHeadings.js';
 export * from './remarkVisibilityForMarkdown.js';

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

@@ -15,10 +15,12 @@ export * from './remarkSplitTabs.js';
 export * from './remarkComponentIds.js';
 export * from './remarkMdxExtractPanel.js';
 export * from './remarkValidateSteps.js';
+export * from './remarkValidateVisibility.js';
 export * from './remarkValidateTabs.js';
 export * from './remarkVideo.js';
 export * from './remarkExtractMultiView.js';
 export * from './remarkPrompt.js';
 export * from './remarkResolveRelativeLinks.js';
+export * from './remarkUnwrapInlineJsx.js';
 export * from './remarkUnwrapJsxHeadings.js';
 export * from './remarkVisibilityForMarkdown.js';

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

@@ -1,6 +1,6 @@
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
-import { visit } from 'unist-util-visit';
+import { SKIP, visit } from 'unist-util-visit';
 import { coreRemarkMdxPlugins } from '../../remark.js';
 export const remarkExtractMultiView = (mdxExtracts) => {
     return (tree) => {
@@ -10,7 +10,10 @@ export const remarkExtractMultiView = (mdxExtracts) => {
             if ('attributes' in sanitized && Array.isArray(sanitized.attributes)) {
                 sanitized.attributes = sanitized.attributes.map((attr) => {
                     if (attr.value != null && typeof attr.value !== 'string') {
-                        return Object.assign(Object.assign({}, attr), { value: String(attr.value) });
+                        const raw = 'value' in attr.value && typeof attr.value.value === 'string'
+                            ? attr.value.value
+                            : String(attr.value);
+                        return Object.assign(Object.assign({}, attr), { value: raw });
                     }
                     return attr;
                 });
@@ -40,7 +43,9 @@ export const remarkExtractMultiView = (mdxExtracts) => {
                 return attribute.value;
             }
             if (typeof attribute.value === 'object' && 'value' in attribute.value) {
-                return String(attribute.value.value);
+                const raw = String(attribute.value.value).trim();
+                const quoted = raw.match(/^(["'`])([\s\S]*)\1$/);
+                return quoted ? quoted[2] : raw;
             }
             return undefined;
         };
@@ -59,7 +64,7 @@ export const remarkExtractMultiView = (mdxExtracts) => {
                         console.warn(`\n⚠️  Duplicate View title: "${title}"\n` +
                             `   Use one View component per title per page. Duplicate Views are ignored.\n` +
                             `   Learn more: https://www.mintlify.com/docs/components/view\n`);
-                        return;
+                        return SKIP;
                     }
                     // Extract the id attribute (set by remarkComponentIds or explicit) so the
                     // client can match URL hashes back to the correct view for shareable links.
@@ -79,10 +84,20 @@ export const remarkExtractMultiView = (mdxExtracts) => {
                     }
                     multiViews.push(viewItem);
                 }
+                else {
+                    console.warn(`\n⚠️  View component is missing a title.\n` +
+                        `   Every View needs a non-empty string title; a View without one is never rendered.\n` +
+                        `   Learn more: https://www.mintlify.com/docs/components/view\n`);
+                }
             }
         });
-        if (mdxExtracts && multiViews.length) {
-            mdxExtracts.multiViewItems = multiViews;
+        if (mdxExtracts) {
+            if (multiViews.length) {
+                mdxExtracts.multiViewItems = multiViews;
+            }
+            else {
+                delete mdxExtracts.multiViewItems;
+            }
         }
         return tree;
     };

package/dist/mdx/plugins/remark/remarkMdxRemoveUnknownJsx/index.d.ts

@@ -1,4 +1,4 @@
 import type { Root } from 'mdast';
 export declare const remarkMdxRemoveUnknownJsx: ({ allowlist }?: {
     allowlist?: string[];
-}) => (tree: Root) => Root | import("mdast").Link | import("mdast").Delete | import("mdast").Code | import("mdast").Blockquote | import("mdast").Break | import("mdast").Definition | import("mdast").Emphasis | import("mdast").FootnoteDefinition | import("mdast").FootnoteReference | import("mdast").Heading | import("mdast").Html | import("mdast").Image | import("mdast").ImageReference | import("mdast").InlineCode | import("mdast").LinkReference | import("mdast").List | import("mdast").ListItem | import("mdast").Paragraph | import("mdast").Strong | import("mdast").Table | import("mdast").TableCell | import("mdast").TableRow | import("mdast").Text | import("mdast").ThematicBreak | import("mdast").Yaml | import("mdast-util-math").InlineMath | import("mdast-util-math").Math | import("mdast-util-mdx-expression").MdxTextExpression | import("mdast-util-mdx-expression").MdxFlowExpression | import("mdast-util-mdx").MdxJsxFlowElement | import("mdast-util-mdx").MdxJsxTextElement | import("mdast-util-mdxjs-esm").MdxjsEsm;
+}) => (tree: Root) => Root | import("mdast").Link | import("mdast").Delete | import("mdast").Code | import("mdast-util-mdx").MdxJsxFlowElement | import("mdast-util-mdx").MdxJsxTextElement | import("mdast").Blockquote | import("mdast").Break | import("mdast").Definition | import("mdast").Emphasis | import("mdast").FootnoteDefinition | import("mdast").FootnoteReference | import("mdast").Heading | import("mdast").Html | import("mdast").Image | import("mdast").ImageReference | import("mdast").InlineCode | import("mdast").LinkReference | import("mdast").List | import("mdast").ListItem | import("mdast").Paragraph | import("mdast").Strong | import("mdast").Table | import("mdast").TableCell | import("mdast").TableRow | import("mdast").Text | import("mdast").ThematicBreak | import("mdast").Yaml | import("mdast-util-math").InlineMath | import("mdast-util-math").Math | import("mdast-util-mdx-expression").MdxTextExpression | import("mdast-util-mdx-expression").MdxFlowExpression | import("mdast-util-mdxjs-esm").MdxjsEsm;

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

@@ -12,7 +12,7 @@ const dedent = (text) => {
 export const remarkPrompt = () => {
     return (tree, file) => {
         const source = String(file.value);
-        visit(tree, 'mdxJsxFlowElement', (node) => {
+        const transformPromptNode = (node) => {
             if (node.name !== 'Prompt')
                 return;
             if (!node.position)
@@ -23,7 +23,7 @@ export const remarkPrompt = () => {
             const endOffset = node.position.end.offset;
             if (startOffset === undefined || endOffset === undefined)
                 return;
-            const nodeSource = source.slice(startOffset, endOffset);
+            const nodeSource = source.slice(startOffset, endOffset).replace(/\r\n?/g, '\n');
             let inString = false;
             let braceDepth = 0;
             let openTagEnd = -1;
@@ -34,7 +34,7 @@ export const remarkPrompt = () => {
                         inString = false;
                     continue;
                 }
-                if (ch === '"' || ch === "'") {
+                if (ch === '"' || ch === "'" || ch === '`') {
                     inString = ch;
                     continue;
                 }
@@ -84,6 +84,8 @@ export const remarkPrompt = () => {
                 },
             });
             node.children = [];
-        });
+        };
+        visit(tree, 'mdxJsxFlowElement', transformPromptNode);
+        visit(tree, 'mdxJsxTextElement', transformPromptNode);
     };
 };

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

@@ -0,0 +1,11 @@
+import type { Root } from 'mdast';
+/**
+ * Unwraps the paragraph MDX generates around the content of inline components
+ * authored in block form (`<Badge>\nBeta\n</Badge>`). Without this, the
+ * paragraph renders inside the component's inline element (`<span><p>`,
+ * `<button><p>`) — invalid HTML that browsers reparse, causing hydration
+ * mismatches. Any other block content (multiple paragraphs, headings,
+ * blockquotes, ...) is left untouched (flattening would silently merge
+ * blocks) and surfaced with a warning instead.
+ */
+export declare const remarkUnwrapInlineJsx: () => (tree: Root) => void;

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

@@ -0,0 +1,26 @@
+import { visit } from 'unist-util-visit';
+const INLINE_JSX_COMPONENTS = new Set(['Badge', 'Tooltip']);
+/**
+ * Unwraps the paragraph MDX generates around the content of inline components
+ * authored in block form (`<Badge>\nBeta\n</Badge>`). Without this, the
+ * paragraph renders inside the component's inline element (`<span><p>`,
+ * `<button><p>`) — invalid HTML that browsers reparse, causing hydration
+ * mismatches. Any other block content (multiple paragraphs, headings,
+ * blockquotes, ...) is left untouched (flattening would silently merge
+ * blocks) and surfaced with a warning instead.
+ */
+export const remarkUnwrapInlineJsx = () => (tree) => {
+    visit(tree, 'mdxJsxFlowElement', (node) => {
+        if (!node.name || !INLINE_JSX_COMPONENTS.has(node.name))
+            return;
+        const [onlyChild] = node.children;
+        if (node.children.length === 1 && (onlyChild === null || onlyChild === void 0 ? void 0 : onlyChild.type) === 'paragraph') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- phrasing content is valid at runtime; mdast types only allow block content here
+            node.children = onlyChild.children;
+            return;
+        }
+        if (node.children.length > 0) {
+            console.warn(`<${node.name}> is an inline component; block-level content inside it renders invalid HTML. Use a single line of content.`);
+        }
+    });
+};

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

@@ -0,0 +1,2 @@
+import type { Root } from 'mdast';
+export declare const remarkValidateVisibility: () => (tree: Root) => void;

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

@@ -0,0 +1,15 @@
+import { visit } from 'unist-util-visit';
+import { isVisibilityElement, resolveVisibilityFor } from './remarkVisibilityForMarkdown.js';
+export const remarkValidateVisibility = () => (tree) => {
+    visit(tree, (node) => {
+        if (!isVisibilityElement(node))
+            return;
+        const resolution = resolveVisibilityFor(node);
+        if (resolution.kind === 'invalid') {
+            console.warn(`<Visibility for="${resolution.raw}"> has an unknown audience — expected "humans" or "agents". The content will be hidden from humans.`);
+        }
+        if (resolution.kind === 'missing') {
+            console.warn('<Visibility> is missing its "for" audience — expected "humans" or "agents". The content will be hidden from humans.');
+        }
+    });
+};

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

@@ -1,2 +1,21 @@
 import type { Root } from 'mdast';
+import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx';
+type MdxJsxElement = MdxJsxFlowElement | MdxJsxTextElement;
+export declare function isVisibilityElement(node: {
+    type: string;
+    name?: string | null;
+}): boolean;
+export type VisibilityResolution = {
+    kind: 'audience';
+    audience: 'humans' | 'agents';
+} | {
+    kind: 'invalid';
+    raw: string;
+} | {
+    kind: 'dynamic';
+} | {
+    kind: 'missing';
+};
+export declare function resolveVisibilityFor(node: MdxJsxElement): VisibilityResolution;
 export declare const remarkVisibilityForMarkdown: () => (tree: Root) => void;
+export {};

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

@@ -1,26 +1,52 @@
+export function isVisibilityElement(node) {
+    return ((node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+        node.name === 'Visibility');
+}
 function isMdxJsxElement(node) {
     return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
 }
-function getVisibilityFor(node) {
+export function resolveVisibilityFor(node) {
+    var _a;
+    let invalidRaw;
+    let sawDynamic = false;
+    let sawAttribute = false;
     for (const attr of node.attributes) {
         if (attr.type !== 'mdxJsxAttribute' || attr.name !== 'for')
             continue;
+        sawAttribute = true;
         if (typeof attr.value === 'string') {
-            if (attr.value === 'humans' || attr.value === 'agents')
-                return attr.value;
+            if (attr.value === 'humans' || attr.value === 'agents') {
+                return { kind: 'audience', audience: attr.value };
+            }
+            invalidRaw !== null && invalidRaw !== void 0 ? invalidRaw : (invalidRaw = attr.value);
             continue;
         }
-        if (attr.value &&
-            typeof attr.value === 'object' &&
-            'value' in attr.value &&
-            typeof attr.value.value === 'string') {
-            const raw = attr.value.value.trim();
-            const quoted = raw.match(/^(["'])(humans|agents)\1$/);
-            if (quoted)
-                return quoted[2];
+        if (attr.value && typeof attr.value === 'object') {
+            if ('value' in attr.value && typeof attr.value.value === 'string') {
+                const raw = attr.value.value.trim();
+                const quoted = raw.match(/^(["'`])((?:\\.|(?!\1)[^\\])*)\1$/);
+                if (quoted) {
+                    const inner = (_a = quoted[2]) !== null && _a !== void 0 ? _a : '';
+                    const isTemplateWithInterpolation = quoted[1] === '`' && inner.includes('${');
+                    if (!isTemplateWithInterpolation) {
+                        if (inner === 'humans' || inner === 'agents') {
+                            return { kind: 'audience', audience: inner };
+                        }
+                        invalidRaw !== null && invalidRaw !== void 0 ? invalidRaw : (invalidRaw = inner);
+                        continue;
+                    }
+                }
+            }
+            sawDynamic = true;
         }
     }
-    return undefined;
+    if (invalidRaw !== undefined)
+        return { kind: 'invalid', raw: invalidRaw };
+    if (sawDynamic)
+        return { kind: 'dynamic' };
+    if (sawAttribute)
+        return { kind: 'missing' };
+    return { kind: 'missing' };
 }
 // `export * from` is intentionally ignored: it exposes no statically-knowable
 // names and creates no page-local JSX bindings in MDX, so there is nothing to
@@ -120,12 +146,15 @@ function collectJsxReferences(node) {
 // `visibleNames`. Usage inside an agents block counts as visible since that
 // content survives into the markdown output.
 function collectJsxUsage(nodes, insideHumans, hiddenNames, visibleNames) {
-    var _a, _b;
+    var _a, _b, _c;
     for (const node of nodes) {
         let childInsideHumans = insideHumans;
         if (isMdxJsxElement(node)) {
             if (node.name === 'Visibility') {
-                if (getVisibilityFor(node) === 'humans')
+                const resolution = resolveVisibilityFor(node);
+                const isHidden = resolution.kind === 'invalid' ||
+                    (resolution.kind === 'audience' && resolution.audience === 'humans');
+                if (isHidden)
                     childInsideHumans = true;
             }
             else {
@@ -140,6 +169,15 @@ function collectJsxUsage(nodes, insideHumans, hiddenNames, visibleNames) {
         if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
             collectEstreeJsxNames((_b = node.data) === null || _b === void 0 ? void 0 : _b.estree, insideHumans ? hiddenNames : visibleNames);
         }
+        // Attribute-embedded usages like `<Card icon={<Logo />}>` also live in estree.
+        if (isMdxJsxElement(node)) {
+            for (const attr of node.attributes) {
+                const expression = attr.type === 'mdxJsxAttribute' ? attr.value : attr;
+                if (expression && typeof expression === 'object' && 'data' in expression) {
+                    collectEstreeJsxNames((_c = expression.data) === null || _c === void 0 ? void 0 : _c.estree, insideHumans ? hiddenNames : visibleNames);
+                }
+            }
+        }
         if ('children' in node && Array.isArray(node.children)) {
             collectJsxUsage(node.children, childInsideHumans, hiddenNames, visibleNames);
         }
@@ -156,13 +194,17 @@ function transformNode(node, esmToStrip) {
         return esmToStrip.has(node) ? [] : [node];
     }
     if (isMdxJsxElement(node) && node.name === 'Visibility') {
-        const audience = getVisibilityFor(node);
-        if (audience === 'humans') {
+        const resolution = resolveVisibilityFor(node);
+        if (resolution.kind === 'audience' && resolution.audience === 'humans') {
             return [];
         }
-        if (audience === 'agents') {
+        if (resolution.kind === 'audience' && resolution.audience === 'agents') {
             return transformChildren(node.children, esmToStrip);
         }
+        if (resolution.kind === 'invalid') {
+            console.warn(`<Visibility for="${resolution.raw}"> has an unknown audience — expected "humans" or "agents". The content was removed from the markdown output.`);
+            return [];
+        }
     }
     if ('children' in node && Array.isArray(node.children)) {
         const next = transformChildren(node.children, esmToStrip);

package/dist/mdx/server-only/getMdx.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { serialize } from '@mintlify/mdx/server';
 import { getTailwindSelectors } from '../../css/tailwind.js';
-import { getMDXOptions, remarkMdxRemoveJs, remarkExpandContent, remarkSplitCodeGroup, remarkSplitTabs, remarkValidateSteps, remarkValidateTabs, } from '../../index.js';
+import { getMDXOptions, remarkMdxRemoveJs, remarkExpandContent, remarkSplitCodeGroup, remarkSplitTabs, remarkValidateSteps, remarkValidateVisibility, remarkValidateTabs, } from '../../index.js';
 import { codeStylingToThemeOrThemes } from '../getCodeStyling.js';
 import { preprocessCustomHeadingIds } from '../preprocessCustomHeadingIds.js';
 import { replaceVariables } from '../replaceVariables.js';
@@ -32,7 +32,12 @@ export function getMdx(_a) {
             path,
         };
         let mdxExtracts = {};
-        let plugins = [remarkValidateSteps, remarkValidateTabs, ...remarkPlugins];
+        let plugins = [
+            remarkValidateSteps,
+            remarkValidateTabs,
+            remarkValidateVisibility,
+            ...remarkPlugins,
+        ];
         if (pageType === 'pdf') {
             plugins = [...plugins, remarkExpandContent, remarkSplitCodeGroup, remarkSplitTabs];
         }