@mintlify/cli 4.0.1743 → 4.0.1745

package/bin/validate/engine.js

@@ -97,20 +97,13 @@ const parseLevel = (file, content, baseDir) => {
 /** Applies every fix that doesn't overlap an earlier fix in the same file, writing each Markdown file only when its fixed content parses at least as well as before. */
 export const applyFixes = (site, diagnostics) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
-    const contents = new Map();
-    const read = (file) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a;
-        if (!contents.has(file)) {
-            contents.set(file, yield fs.readFile(path.join(site.baseDir, file), 'utf-8'));
-        }
-        return (_a = contents.get(file)) !== null && _a !== void 0 ? _a : '';
-    });
+    const read = (file) => { var _a; return (_a = site.read(file)) !== null && _a !== void 0 ? _a : ''; };
     const chosen = new Map();
     const overlaps = ({ file, start, end }) => { var _a; return ((_a = chosen.get(file)) !== null && _a !== void 0 ? _a : []).some(({ fix }) => start < fix.end && fix.start < end); };
     for (const { rule, fix } of diagnostics) {
         if (!fix || overlaps(fix))
             continue;
-        const content = yield read(fix.file);
+        const content = read(fix.file);
         const change = Object.assign(Object.assign({ rule, file: fix.file }, toPosition(content, fix.start)), { before: content.slice(fix.start, fix.end), after: fix.text });
         chosen.set(fix.file, [...((_a = chosen.get(fix.file)) !== null && _a !== void 0 ? _a : []), { fix, change }]);
     }
@@ -118,7 +111,7 @@ export const applyFixes = (site, diagnostics) => __awaiter(void 0, void 0, void
     const level = (file, content) => parseLevel(file, snippets.has(file) ? replaceVariables(content, site.variables) : content, site.baseDir);
     const applied = [];
     for (const [file, picks] of chosen) {
-        const content = yield read(file);
+        const content = read(file);
         const updated = applyEdits(content, selectEdits(picks.map(({ fix }) => fix)));
         if (/\.mdx?$/.test(file) && level(file, updated) < level(file, content)) {
             continue;
@@ -136,7 +129,7 @@ const MAX_FIX_PASSES = 5;
  */
 export const checkSite = (baseDir, rules, options) => __awaiter(void 0, void 0, void 0, function* () {
     const fixed = [];
-    const site = yield loadSite(baseDir, options);
+    let site = yield loadSite(baseDir, options);
     const { selected } = options;
     if (selected && !site.files.some(({ file }) => selected.has(file))) {
         throw new UsageError(`none of the given files are pages or snippets of this site: ${[...selected].join(', ')}`);
@@ -151,11 +144,11 @@ export const checkSite = (baseDir, rules, options) => __awaiter(void 0, void 0,
         if (changes.length === 0)
             break;
         fixed.push(...changes);
+        site = yield loadSite(baseDir, options);
         const changed = new Set(changes.map(({ file }) => file));
         pending = sortDiagnostics(yield checkFiles(Object.assign(Object.assign({}, site), { selected: changed }), fileRulesOf(rules)));
     }
     if (fixed.length === 0)
         return { site, diagnostics, fixed };
-    const fixedSite = yield loadSite(baseDir, options);
-    return { site: fixedSite, diagnostics: yield runChecks(fixedSite, rules), fixed };
+    return { site, diagnostics: yield runChecks(site, rules), fixed };
 });

package/bin/validate/files.js

@@ -20,22 +20,8 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { getAST, getFileCategory, parseFrontmatter, replaceVariables } from '@mintlify/common';
 import { categorizeMdxFiles, getErrorPosition, getMintIgnore, listContentFiles, } from '@mintlify/prebuild';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { applyEdits, parseContent, relocate, selectEdits, unmapEdit } from './mdx.js';
+import { applyEdits, collectAnchorLinks, parseContent, relocate, selectEdits, unmapEdit, } from './mdx.js';
 import { PARSE_ERROR } from './rules/parseError.js';
-const CONCURRENCY = 16;
-const mapLimit = (items, task) => __awaiter(void 0, void 0, void 0, function* () {
-    const results = new Array(items.length);
-    let next = 0;
-    yield Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, () => __awaiter(void 0, void 0, void 0, function* () {
-        while (next < items.length) {
-            const index = next++;
-            results[index] = yield task(items[index]);
-        }
-    })));
-    return results;
-});
 const CHECKED_CATEGORIES = new Set(['page', 'snippet', 'snippet-v2']);
 export const readSiteFiles = (baseDir) => __awaiter(void 0, void 0, void 0, function* () {
     const { mdxCandidates: candidates } = yield listContentFiles(baseDir, yield getMintIgnore(baseDir));
@@ -74,8 +60,8 @@ const tryParseContent = (content) => {
         return undefined;
     }
 };
-export const parseFile = (file, content, baseDir) => {
-    const context = { file, content, baseDir, frontmatter: readFrontmatter(content) };
+export const parseFile = (file, content, baseDir, extras = {}) => {
+    const context = Object.assign({ file, content, baseDir, frontmatter: readFrontmatter(content) }, extras);
     const tree = tryParseContent(content);
     if (tree)
         return { context: Object.assign(Object.assign({}, context), { tree }), approximate: false };
@@ -102,7 +88,7 @@ const toDiagnostic = (rule, file, _a, stages, stage) => {
     const original = edit && unmapEdit(stages, stage, edit);
     return Object.assign(Object.assign(Object.assign(Object.assign({}, finding), relocate(stages, stage, finding)), { rule: rule.id, group: rule.group, severity: rule.severity, file }), (original && { fix: Object.assign({ file }, original) }));
 };
-const checkFile = (allRules, { file, kind }, content, baseDir, variables) => {
+const checkFile = (allRules, { file, kind }, content, baseDir, extras, variables) => {
     const rules = kind === 'snippet' ? allRules.filter((rule) => !rule.pagesOnly) : allRules;
     const raw = rules.filter((rule) => rule.raw);
     const treeRules = rules.filter((rule) => !rule.raw);
@@ -118,7 +104,7 @@ const checkFile = (allRules, { file, kind }, content, baseDir, variables) => {
         { content: afterRaw, edits: [] },
     ];
     const diagnostics = rawFound.map(({ rule, finding }) => toDiagnostic(rule, file, finding, stages, SOURCE_STAGE));
-    const parsed = parseFile(file, afterRaw, baseDir);
+    const parsed = parseFile(file, afterRaw, baseDir, extras);
     if ('error' in parsed) {
         diagnostics.unshift(parseErrorDiagnostic(file, Object.assign(Object.assign({}, parsed.error), relocate(stages, AFTER_RAW_STAGE, parsed.error))));
         return diagnostics;
@@ -131,18 +117,28 @@ const checkFile = (allRules, { file, kind }, content, baseDir, variables) => {
     }
     return diagnostics;
 };
+const collectSiteAnchorLinks = (site) => __awaiter(void 0, void 0, void 0, function* () {
+    const pages = yield Promise.all(site.files.map(({ file }) => { var _a; return collectAnchorLinks(file, (_a = site.read(file)) !== null && _a !== void 0 ? _a : ''); }));
+    return new Set(pages.flat());
+});
 export const checkFiles = (site, rules) => __awaiter(void 0, void 0, void 0, function* () {
+    const anchorRules = new Set(rules.filter((rule) => rule.needsAnchorLinks).map(({ id }) => id));
     const targets = site.files.filter(({ file }) => !site.selected || site.selected.has(file));
-    const results = yield mapLimit(targets, (entry) => __awaiter(void 0, void 0, void 0, function* () {
-        let content;
-        try {
-            content = yield fs.readFile(path.join(site.baseDir, entry.file), 'utf-8');
+    const checkTarget = (entry, extras) => {
+        const content = site.read(entry.file);
+        if (content === undefined) {
+            return [parseErrorDiagnostic(entry.file, { message: 'could not read this file' })];
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'could not read this file';
-            return [parseErrorDiagnostic(entry.file, { message })];
-        }
-        return checkFile(rules, entry, content, site.baseDir, site.variables);
-    }));
-    return results.flat();
+        return checkFile(rules, entry, content, site.baseDir, extras, site.variables);
+    };
+    const needsLinks = (diagnostics) => diagnostics.some(({ rule }) => anchorRules.has(rule));
+    const checked = targets.map((entry) => checkTarget(entry, { readFile: site.read }));
+    if (!checked.some(needsLinks))
+        return checked.flat();
+    const extras = { readFile: site.read, anchorLinks: yield collectSiteAnchorLinks(site) };
+    return targets.flatMap((entry, index) => {
+        var _a;
+        const diagnostics = (_a = checked[index]) !== null && _a !== void 0 ? _a : [];
+        return needsLinks(diagnostics) ? checkTarget(entry, extras) : diagnostics;
+    });
 });

package/bin/validate/mdx.js

@@ -1,4 +1,14 @@
-import { coreRemark, FRONTMATTER_RE, getCodeRanges, HEADING_ID_RE, JSXParser, } from '@mintlify/common';
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { coreRemark, FRONTMATTER_RE, getCodeRanges, HEADING_ID_RE, JSXParser, pagePathToSlug, replaceSlashIndex, safeCleanHeadingId, toPosixPath, } from '@mintlify/common';
+import { decorateGraphNodeFromPageContent, Node, PathType } from '@mintlify/link-rot';
 const HEADING_ID = new RegExp(HEADING_ID_RE.source, 'gm');
 const ESM_START = /^(?:import|export)(?=[\s{*])/;
 const JSX_TAG = /<[A-Za-z][\w.:-]*(?:"[^"]*"|'[^']*'|\{[^{}]*\}|[^<>"'{}])*>/g;
@@ -199,3 +209,30 @@ export const relocate = (stages, index, position) => {
     const mapped = toPosition(original.content, offset);
     return position.column === undefined ? { line: mapped.line } : mapped;
 };
+const pagePath = (file) => replaceSlashIndex(pagePathToSlug(file)).replace(/^\.$/, '');
+export const collectAnchorLinks = (file, content) => __awaiter(void 0, void 0, void 0, function* () {
+    const node = new Node(file);
+    try {
+        yield decorateGraphNodeFromPageContent(node, content);
+    }
+    catch (_a) {
+        return [];
+    }
+    return node.paths.flatMap((link) => link.pathType === PathType.INTERNAL && link.anchorLink
+        ? [
+            `${pagePath(toPosixPath(link.toString()))}#${safeCleanHeadingId(link.anchorLink.slice(1))}`,
+        ]
+        : []);
+});
+export const linkedAnchor = (links, file, slug) => {
+    const prefix = `${pagePath(file)}#`;
+    for (const link of links !== null && links !== void 0 ? links : []) {
+        if (!link.startsWith(prefix))
+            continue;
+        const anchor = link.slice(prefix.length);
+        const suffix = anchor.startsWith(`${slug}-`) && /^\d/.test(anchor.slice(slug.length + 1));
+        if (anchor === slug || suffix)
+            return anchor;
+    }
+    return undefined;
+};

package/bin/validate/rules/build.js

@@ -17,20 +17,28 @@ const IMPORT_TYPES = new Set([
 ]);
 const POSITION = /^:(\d+)(?::(\d+))?/;
 const QUOTED = /"([^"]+)"/;
-const toFinding = (site, { type, message }) => {
-    var _a;
-    const clean = stripVTControlCharacters(message).trim();
-    const importer = IMPORT_TYPES.has(type)
+const toFinding = (site, warning) => {
+    var _a, _b;
+    const clean = stripVTControlCharacters(warning.message).trim();
+    const importer = warning.file == null && IMPORT_TYPES.has(warning.type)
         ? IMPORTERS.map((pattern) => { var _a; return (_a = pattern.exec(clean)) === null || _a === void 0 ? void 0 : _a[1]; }).find(Boolean)
         : undefined;
     // Missing nav pages are always about the config, even when the page looks like a file
-    const match = importer || type === 'missing-nav-page' ? null : FILE_IN_MESSAGE.exec(clean);
+    const match = warning.file != null || importer || warning.type === 'missing-nav-page'
+        ? null
+        : FILE_IN_MESSAGE.exec(clean);
     const found = importer !== null && importer !== void 0 ? importer : match === null || match === void 0 ? void 0 : match[0];
-    const file = found ? normalizeRelativePath(toPosixPath(found)) : site.configFile;
+    const file = (_a = warning.file) !== null && _a !== void 0 ? _a : (found ? normalizeRelativePath(toPosixPath(found)) : site.configFile);
     const position = match ? POSITION.exec(clean.slice(match.index + match[0].length)) : null;
     // Config warnings quote the entry they're about, such as a navigation page
-    const quoted = file === site.configFile ? (_a = QUOTED.exec(clean)) === null || _a === void 0 ? void 0 : _a[0] : undefined;
-    return Object.assign(Object.assign(Object.assign({ file }, (position && Object.assign({ line: Number(position[1]) }, (position[2] && { column: Number(position[2]) })))), (quoted && site.locate(file, quoted))), { message: clean });
+    const quoted = warning.file == null && file === site.configFile ? (_b = QUOTED.exec(clean)) === null || _b === void 0 ? void 0 : _b[0] : undefined;
+    const located = warning.ref != null && warning.line == null
+        ? site.locate(file, JSON.stringify(warning.ref))
+        : quoted
+            ? site.locate(file, quoted)
+            : undefined;
+    return Object.assign(Object.assign(Object.assign({ file }, (warning.line != null
+        ? Object.assign({ line: warning.line }, (warning.column != null && { column: warning.column })) : position && Object.assign({ line: Number(position[1]) }, (position[2] && { column: Number(position[2]) })))), located), { message: clean });
 };
 /** Warning types some rule turns into diagnostics, so a strict-build failure is explained. */
 const COVERED_TYPES = new Set(['parse-error']);

package/bin/validate/rules/content/duplicateH1.js

@@ -0,0 +1,57 @@
+import { AVOIDED_PAGE_MODES, getTableOfContentsTitle, safeCleanHeadingId, slugify, } from '@mintlify/common';
+import remarkSmartypants from 'remark-smartypants';
+import { unified } from 'unified';
+import { hasCustomHeadingId, linkedAnchor } from '../../mdx.js';
+const normalize = (value) => value.trim().replace(/\s+/g, ' ');
+const smartypants = unified().use(remarkSmartypants);
+const firstHeading = (tree) => tree.children.find((node) => node.type === 'heading');
+const renderedText = (heading) => {
+    const clone = structuredClone(heading);
+    const root = { type: 'root', children: [clone] };
+    smartypants.runSync(root);
+    return getTableOfContentsTitle(clone);
+};
+export const duplicateH1 = {
+    id: 'duplicate-h1',
+    group: 'content',
+    severity: 'warning',
+    scope: 'file',
+    description: 'remove a first heading that repeats the frontmatter title',
+    pagesOnly: true,
+    needsAnchorLinks: true,
+    check: ({ tree, frontmatter, content, file, anchorLinks }) => {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const { title, mode } = frontmatter;
+        if (typeof title !== 'string' || AVOIDED_PAGE_MODES.includes(String(mode)))
+            return [];
+        const first = firstHeading(tree);
+        if (!first || first.depth !== 1)
+            return [];
+        if (normalize(getTableOfContentsTitle(first)) !== normalize(title))
+            return [];
+        const start = (_b = (_a = first.position) === null || _a === void 0 ? void 0 : _a.start.offset) !== null && _b !== void 0 ? _b : 0;
+        const end = (_d = (_c = first.position) === null || _c === void 0 ? void 0 : _c.end.offset) !== null && _d !== void 0 ? _d : start;
+        const location = {
+            line: (_e = first.position) === null || _e === void 0 ? void 0 : _e.start.line,
+            column: (_f = first.position) === null || _f === void 0 ? void 0 : _f.start.column,
+        };
+        const lineEnd = content.indexOf('\n', start);
+        if (hasCustomHeadingId(content.slice(start, lineEnd === -1 ? undefined : lineEnd))) {
+            return [
+                Object.assign(Object.assign({}, location), { message: 'first heading duplicates the frontmatter title; it has a custom {#id}, so remove it by hand and update links to it' }),
+            ];
+        }
+        const anchor = [renderedText(first), getTableOfContentsTitle(first)]
+            .map((text) => linkedAnchor(anchorLinks, file, safeCleanHeadingId(slugify(text))))
+            .find((linked) => linked !== undefined);
+        if (anchor !== undefined) {
+            return [
+                Object.assign(Object.assign({}, location), { message: `first heading duplicates the frontmatter title; links point to #${anchor}, so remove it by hand and update them` }),
+            ];
+        }
+        const trailing = (_h = (_g = /^\n*/.exec(content.slice(end))) === null || _g === void 0 ? void 0 : _g[0].length) !== null && _h !== void 0 ? _h : 0;
+        return [
+            Object.assign(Object.assign({}, location), { message: 'first heading duplicates the frontmatter title', edit: { start, end: end + trailing, text: '' } }),
+        ];
+    },
+};

package/bin/validate/rules/content/foreignSyntax.js

@@ -0,0 +1,120 @@
+import { maskCode, maskFrontmatter, maskNonMarkup, toPosition } from '../../mdx.js';
+const CALLOUTS = {
+    note: '<Note>',
+    info: '<Info>',
+    tip: '<Tip>',
+    hint: '<Tip>',
+    success: '<Check>',
+    important: '<Note>',
+    warning: '<Warning>',
+    caution: '<Warning>',
+    danger: '<Warning>',
+    error: '<Warning>',
+    details: '<Accordion>',
+};
+const callout = (name) => { var _a, _b; return (_b = CALLOUTS[(_a = name === null || name === void 0 ? void 0 : name.toLowerCase()) !== null && _a !== void 0 ? _a : '']) !== null && _b !== void 0 ? _b : 'a callout (<Note>, <Info>, <Tip> or <Warning>)'; };
+const LIQUID_TAGS = {
+    hint: 'a callout (<Note>, <Info>, <Tip> or <Warning>)',
+    tabs: '<Tabs>',
+    tab: '<Tab title="…">',
+    stepper: '<Steps>',
+    step: '<Step title="…">',
+    embed: 'a link or <Frame>',
+    'content-ref': '<Card>',
+    include: 'a snippet import',
+    code: 'a fenced code block',
+    file: 'a link to the file',
+    swagger: 'an OpenAPI page',
+    openapi: 'an OpenAPI page',
+};
+const PATTERNS = [
+    {
+        regex: /\{%-?\s*(?!end)([\w-]+)[^%\n]*?-?%\}/g,
+        message: ([tag, name]) => {
+            var _a, _b;
+            const style = name === 'hint' ? (_a = /style=["']?(\w+)/.exec(tag)) === null || _a === void 0 ? void 0 : _a[1] : undefined;
+            const target = style
+                ? callout(style)
+                : ((_b = LIQUID_TAGS[name !== null && name !== void 0 ? name : '']) !== null && _b !== void 0 ? _b : 'Markdown or a Mintlify component');
+            return `${tag} is a GitBook or Liquid tag, which Mintlify does not support; use ${target}`;
+        },
+    },
+    {
+        regex: /\{\{[<%]\s*([\w/-]+)[^}\n]*[>%]\}\}/g,
+        message: ([tag]) => `${tag} is a Hugo shortcode, which Mintlify does not support; use Markdown or a Mintlify component`,
+    },
+    {
+        regex: /\{\{-?\s*(?:(?:site|page|layout|include|jekyll|paginator)\.[^}\n]*|[^\s|{}]+\s*\|\s*\w+[^}\n]*)-?\}\}/g,
+        message: ([tag]) => `${tag} is a Liquid variable, which Mintlify does not support; write the value, or use a snippet or a variable`,
+    },
+    {
+        regex: /^ {0,3}:{3,}\s*([A-Za-z][\w-]*)/gm,
+        message: ([, name]) => `:::${name} is a Docusaurus or VitePress admonition, which Mintlify does not support; use ${callout(name)}`,
+    },
+    {
+        regex: /^ {0,3}::(?!:)([A-Za-z][\w-]*)/gm,
+        message: ([, name]) => `::${name} is an MDC (Nuxt Content, Docus) block, which Mintlify does not support; use the matching Mintlify component`,
+    },
+    {
+        regex: /^ {0,3}(!!!|\?\?\?\+?)[ \t]+([A-Za-z][\w-]*)/gm,
+        message: ([, marker, name]) => `${marker} ${name} is an MkDocs admonition, which Mintlify does not support; use ${marker === '!!!' ? callout(name) : '<Accordion>'}`,
+    },
+    {
+        regex: /^ {0,3}===\+?[ \t]+["']/gm,
+        message: () => `=== "…" is an MkDocs content tab, which Mintlify does not support; use <Tabs> with <Tab title="…">`,
+    },
+    {
+        regex: /^[ \t]*;?[ \t]*--8<--/gm,
+        scope: 'everything',
+        message: () => '--8<-- is an MkDocs snippet include, which Mintlify does not support; use a snippet import or paste the content',
+    },
+    {
+        regex: /\{:\s*[.#\w][^}\n]*\}/g,
+        message: ([list]) => `${list} is a Kramdown attribute list, which Mintlify does not support; remove it, use a component, or use {#id} for a heading anchor`,
+    },
+    {
+        regex: /(?<![[{\w])\[\[([^[\]\n]+)\]\](?![(:[])/g,
+        message: ([link]) => `${link} is a wiki link, which Mintlify does not support; use a Markdown link such as [text](/path)`,
+    },
+    {
+        regex: /(?:\]\(|href=["'])((?:doc|ref|blog|changelog|page):[^)\s"']+)/g,
+        scope: 'links',
+        message: ([, link]) => {
+            var _a;
+            return `${link} is a ReadMe link, which Mintlify does not support; link to the page path instead, such as /${(_a = link === null || link === void 0 ? void 0 : link.split(':')[1]) !== null && _a !== void 0 ? _a : ''}`;
+        },
+    },
+    {
+        regex: /["'(]@site\/[^"')\s]*/g,
+        scope: 'prose-and-esm',
+        message: ([path]) => `${path.slice(1)} uses the Docusaurus @site alias, which Mintlify does not resolve; use a root-relative path such as /images/… or /snippets/…`,
+    },
+];
+export const foreignSyntax = {
+    id: 'foreign-syntax',
+    group: 'content',
+    severity: 'warning',
+    scope: 'file',
+    description: "syntax from another docs framework that Mintlify doesn't render",
+    raw: true,
+    check: ({ content }) => {
+        const prose = maskCode(content);
+        const literal = maskNonMarkup(content);
+        const views = {
+            prose,
+            links: prose,
+            'prose-and-esm': maskCode(content, { keepEsm: true }),
+            everything: maskFrontmatter(content),
+        };
+        const issues = [];
+        for (const { regex, scope = 'prose', message } of PATTERNS) {
+            for (const match of views[scope].matchAll(regex)) {
+                const start = match.index + (match[0].length - match[0].trimStart().length);
+                if (scope === 'prose' && literal[start] !== prose[start])
+                    continue;
+                issues.push(Object.assign(Object.assign({}, toPosition(content, start)), { message: message(match) }));
+            }
+        }
+        return issues;
+    },
+};

package/bin/validate/rules/content/katex.js

@@ -0,0 +1,34 @@
+import { isCurrencyMath } from '@mintlify/common';
+import katex from 'katex';
+import { visit } from 'unist-util-visit';
+export const katexRule = {
+    id: 'katex',
+    group: 'content',
+    severity: 'warning',
+    scope: 'file',
+    description: "math that KaTeX can't render",
+    check: ({ tree, content }) => {
+        const issues = [];
+        visit(tree, (node) => {
+            var _a, _b;
+            if (node.type !== 'math' && node.type !== 'inlineMath')
+                return;
+            if (node.type === 'inlineMath' && isCurrencyMath(node, content))
+                return;
+            try {
+                katex.renderToString(node.value, {
+                    throwOnError: true,
+                    displayMode: node.type === 'math',
+                });
+            }
+            catch (error) {
+                issues.push({
+                    line: (_a = node.position) === null || _a === void 0 ? void 0 : _a.start.line,
+                    column: (_b = node.position) === null || _b === void 0 ? void 0 : _b.start.column,
+                    message: error instanceof Error ? error.message : 'invalid math',
+                });
+            }
+        });
+        return issues;
+    },
+};

package/bin/validate/rules/content/unknownComponent.js

@@ -0,0 +1,121 @@
+import { collectPatternNames, collectExportedNames, getAST, isBuiltInComponent, JSX_EXTENSIONS, visitReferences, } from '@mintlify/common';
+import { visit } from 'unist-util-visit';
+const getDeclared = (context) => {
+    const declared = new Set();
+    visit(context.tree, 'mdxjsEsm', (node) => {
+        var _a, _b, _c;
+        for (const statement of (_c = (_b = (_a = node.data) === null || _a === void 0 ? void 0 : _a.estree) === null || _b === void 0 ? void 0 : _b.body) !== null && _c !== void 0 ? _c : []) {
+            if (statement.type === 'ImportDeclaration') {
+                for (const specifier of statement.specifiers) {
+                    collectPatternNames(specifier.local, declared);
+                }
+            }
+            else if (statement.type === 'ExportNamedDeclaration') {
+                const declaration = statement.declaration;
+                if ((declaration === null || declaration === void 0 ? void 0 : declaration.type) === 'VariableDeclaration') {
+                    for (const declarator of declaration.declarations) {
+                        collectPatternNames(declarator.id, declared);
+                    }
+                }
+                else if (declaration) {
+                    collectPatternNames(declaration.id, declared);
+                }
+                for (const specifier of statement.specifiers) {
+                    collectPatternNames(specifier.local, declared);
+                    collectPatternNames(specifier.exported, declared);
+                }
+            }
+            else if (statement.type === 'ExportDefaultDeclaration') {
+                const declaration = statement.declaration;
+                if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
+                    collectPatternNames(declaration.id, declared);
+                }
+            }
+        }
+    });
+    return declared;
+};
+const getImportPosition = (context) => {
+    var _a, _b;
+    const frontmatter = context.tree.children.find((child) => ['yaml', 'toml'].includes(child.type));
+    return (_b = (_a = frontmatter === null || frontmatter === void 0 ? void 0 : frontmatter.position) === null || _a === void 0 ? void 0 : _a.end.offset) !== null && _b !== void 0 ? _b : 0;
+};
+const getSpecifier = (snippet, file, name) => {
+    let exported;
+    try {
+        exported = collectExportedNames(getAST(snippet, file));
+    }
+    catch (_a) {
+        return undefined;
+    }
+    if (exported.has(name))
+        return `{ ${name} }`;
+    return exported.has('default') ? name : undefined;
+};
+export const unknownComponent = {
+    id: 'unknown-component',
+    group: 'content',
+    severity: 'warning',
+    scope: 'file',
+    description: 'JSX components that are not built in, imported or exported',
+    pagesOnly: true,
+    check: (context) => {
+        var _a, _b;
+        const declared = getDeclared(context);
+        const reported = new Set();
+        const issues = [];
+        const insertAt = getImportPosition(context);
+        const prefix = insertAt === 0 ? '' : '\n\n';
+        const following = (_b = (_a = /^\n*/.exec(context.content.slice(insertAt))) === null || _a === void 0 ? void 0 : _a[0].length) !== null && _b !== void 0 ? _b : 0;
+        const suffix = '\n'.repeat(Math.max(0, 2 - following));
+        const check = (tag, position) => {
+            var _a;
+            const name = tag === null || tag === void 0 ? void 0 : tag.split('.')[0];
+            if (!tag || !name || !/^[A-Z]/.test(name))
+                return;
+            if (declared.has(name) || reported.has(tag) || isBuiltInComponent(tag))
+                return;
+            reported.add(tag);
+            const file = JSX_EXTENSIONS.map((extension) => `snippets/${name}${extension}`).find((candidate) => { var _a; return ((_a = context.readFile) === null || _a === void 0 ? void 0 : _a.call(context, candidate)) !== undefined; });
+            const source = file && ((_a = context.readFile) === null || _a === void 0 ? void 0 : _a.call(context, file));
+            const specifier = file && source !== undefined && tag === name ? getSpecifier(source, file, name) : undefined;
+            issues.push({
+                line: position === null || position === void 0 ? void 0 : position.line,
+                column: position === null || position === void 0 ? void 0 : position.column,
+                message: `<${tag}> is not built in, imported or exported on this page`,
+                edit: specifier
+                    ? {
+                        start: insertAt,
+                        end: insertAt,
+                        text: `${prefix}import ${specifier} from "/${file}";${suffix}`,
+                    }
+                    : undefined,
+            });
+        };
+        const checkJsxInExpression = (estree, fallback) => visitReferences(estree, new Set(), {
+            reference: (identifier) => {
+                var _a;
+                if (identifier.type !== 'JSXIdentifier')
+                    return;
+                const loc = identifier.loc;
+                check(String(identifier.name), (_a = loc === null || loc === void 0 ? void 0 : loc.start) !== null && _a !== void 0 ? _a : fallback);
+            },
+        });
+        visit(context.tree, (node) => {
+            var _a, _b, _c, _d, _e;
+            if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+                check(node.name, (_a = node.position) === null || _a === void 0 ? void 0 : _a.start);
+                for (const attribute of node.attributes) {
+                    const value = attribute.type === 'mdxJsxAttribute' ? attribute.value : attribute;
+                    if (value && typeof value === 'object') {
+                        checkJsxInExpression((_b = value.data) === null || _b === void 0 ? void 0 : _b.estree, (_c = node.position) === null || _c === void 0 ? void 0 : _c.start);
+                    }
+                }
+            }
+            else if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+                checkJsxInExpression((_d = node.data) === null || _d === void 0 ? void 0 : _d.estree, (_e = node.position) === null || _e === void 0 ? void 0 : _e.start);
+            }
+        });
+        return issues;
+    },
+};

package/bin/validate/rules/index.js

@@ -1,5 +1,17 @@
 import { BUILD_RULES } from './build.js';
+import { duplicateH1 } from './content/duplicateH1.js';
+import { foreignSyntax } from './content/foreignSyntax.js';
+import { katexRule } from './content/katex.js';
+import { unknownComponent } from './content/unknownComponent.js';
 import { voidTags } from './content/voidTags.js';
 import { openApiSpec } from './openapi.js';
 /** Every check mint validate runs, in report order. */
-export const RULES = [voidTags, openApiSpec, ...BUILD_RULES];
+export const RULES = [
+    voidTags,
+    duplicateH1,
+    unknownComponent,
+    katexRule,
+    foreignSyntax,
+    openApiSpec,
+    ...BUILD_RULES,
+];

package/bin/validate/site.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { existsSync, readFileSync } from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 import { readSiteFiles } from './files.js';
 import { toPosition } from './mdx.js';
@@ -24,30 +24,32 @@ const readVariables = (config) => {
 };
 /** Lists the site's pages and snippets; locate reads files from disk on demand. */
 export const loadSite = (baseDir_1, _a) => __awaiter(void 0, [baseDir_1, _a], void 0, function* (baseDir, { selected, localSchema }) {
+    var _b;
     const files = yield readSiteFiles(baseDir);
     const byPath = new Map();
-    const configFile = existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
+    const configFile = fs.existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
     const read = (file) => {
-        var _a;
         if (!byPath.has(file)) {
             try {
-                byPath.set(file, readFileSync(path.join(baseDir, file), 'utf-8'));
+                byPath.set(file, fs.readFileSync(path.join(baseDir, file), 'utf-8'));
             }
-            catch (_b) {
-                byPath.set(file, '');
+            catch (_a) {
+                byPath.set(file, undefined);
             }
         }
-        return (_a = byPath.get(file)) !== null && _a !== void 0 ? _a : '';
+        return byPath.get(file);
     };
     return {
         baseDir,
         files,
         selected,
         configFile,
-        variables: readVariables(read(configFile)),
+        variables: readVariables((_b = read(configFile)) !== null && _b !== void 0 ? _b : ''),
         localSchema,
+        read,
         locate: (file, text) => {
-            const content = read(file);
+            var _a;
+            const content = (_a = read(file)) !== null && _a !== void 0 ? _a : '';
             const offset = text ? content.indexOf(text) : -1;
             return offset === -1 ? {} : toPosition(content, offset);
         },