@mintlify/common 1.0.1021 → 1.0.1023

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

@@ -15,6 +15,7 @@ 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';

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

@@ -15,6 +15,7 @@ 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';

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/remarkMermaid.js

@@ -2,6 +2,8 @@ import { visit } from 'unist-util-visit';
 import { MetaOptions } from '../rehype/rehypeCodeBlocks/metaOptions.js';
 const REACT_COMPONENT_NAME = 'Mermaid';
 const RESERVED_KEYS = ['placement', 'actions'];
+const MERMAID_PLACEMENTS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+const DEFAULT_MERMAID_PLACEMENT = 'bottom-right';
 export const remarkMermaid = () => (tree) => {
     var _a;
     const codeblocks = [];
@@ -49,11 +51,16 @@ export const remarkMermaid = () => (tree) => {
                 },
             ];
             if (placement) {
-                attributes.push({
-                    type: 'mdxJsxAttribute',
-                    name: 'placement',
-                    value: placement,
-                });
+                if (MERMAID_PLACEMENTS.includes(placement)) {
+                    attributes.push({
+                        type: 'mdxJsxAttribute',
+                        name: 'placement',
+                        value: placement,
+                    });
+                }
+                else {
+                    console.warn(`Invalid mermaid placement "${placement}" — expected one of: ${MERMAID_PLACEMENTS.join(', ')}. Falling back to ${DEFAULT_MERMAID_PLACEMENT}.`);
+                }
             }
             if (actions !== undefined) {
                 attributes.push({

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];
         }