@mintlify/cli 4.0.1743 → 4.0.1745

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1743",
+  "version": "4.0.1745",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1308",
-    "@mintlify/link-rot": "3.0.1539",
+    "@mintlify/common": "1.0.1310",
+    "@mintlify/link-rot": "3.0.1541",
     "@mintlify/models": "0.0.379",
-    "@mintlify/og": "0.0.107",
-    "@mintlify/prebuild": "1.0.1475",
-    "@mintlify/previewing": "4.0.1557",
+    "@mintlify/og": "0.0.109",
+    "@mintlify/prebuild": "1.0.1477",
+    "@mintlify/previewing": "4.0.1559",
     "@mintlify/validation": "0.1.944",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -60,6 +60,7 @@
     "ink": "6.3.0",
     "inquirer": "12.3.0",
     "js-yaml": "4.3.1",
+    "katex": "0.16.47",
     "mdast-util-mdx-jsx": "3.2.0",
     "open": "8.4.2",
     "openid-client": "6.8.2",
@@ -71,6 +72,7 @@
     "remark-gfm": "4.0.1",
     "remark-math": "6.0.0",
     "remark-mdx": "3.1.1",
+    "remark-smartypants": "3.0.2",
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
     "unist-util-visit": "5.0.0",
@@ -82,7 +84,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.581",
+    "@mintlify/editor": "0.0.583",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/detect-port": "1.3.2",
@@ -101,5 +103,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "99bdeb982e7e885b9293486de337557eb5f89205"
+  "gitHead": "7c0206add0761d1ed8d623e11e9d9a0b9c010663"
 }

package/src/validate/engine.ts

@@ -131,20 +131,14 @@ const parseLevel = (file: string, content: string, baseDir: string) => {
 
 /** 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 = async (site: Site, diagnostics: Diagnostic[]): Promise<Change[]> => {
-  const contents = new Map<string, string>();
-  const read = async (file: string) => {
-    if (!contents.has(file)) {
-      contents.set(file, await fs.readFile(path.join(site.baseDir, file), 'utf-8'));
-    }
-    return contents.get(file) ?? '';
-  };
+  const read = (file: string) => site.read(file) ?? '';
   const chosen = new Map<string, { fix: FileEdit; change: Change }[]>();
   const overlaps = ({ file, start, end }: FileEdit) =>
     (chosen.get(file) ?? []).some(({ fix }) => start < fix.end && fix.start < end);
 
   for (const { rule, fix } of diagnostics) {
     if (!fix || overlaps(fix)) continue;
-    const content = await read(fix.file);
+    const content = read(fix.file);
     const change = {
       rule,
       file: fix.file,
@@ -167,7 +161,7 @@ export const applyFixes = async (site: Site, diagnostics: Diagnostic[]): Promise
 
   const applied: Change[] = [];
   for (const [file, picks] of chosen) {
-    const content = await 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;
@@ -191,7 +185,7 @@ export const checkSite = async (
   options: { selected?: ReadonlySet<string>; localSchema: boolean; fix: boolean }
 ) => {
   const fixed: Change[] = [];
-  const site = await loadSite(baseDir, options);
+  let site = await loadSite(baseDir, options);
   const { selected } = options;
   if (selected && !site.files.some(({ file }) => selected.has(file))) {
     throw new UsageError(
@@ -207,10 +201,10 @@ export const checkSite = async (
     const changes = await applyFixes(site, pending);
     if (changes.length === 0) break;
     fixed.push(...changes);
+    site = await loadSite(baseDir, options);
     const changed = new Set(changes.map(({ file }) => file));
     pending = sortDiagnostics(await checkFiles({ ...site, selected: changed }, fileRulesOf(rules)));
   }
   if (fixed.length === 0) return { site, diagnostics, fixed };
-  const fixedSite = await loadSite(baseDir, options);
-  return { site: fixedSite, diagnostics: await runChecks(fixedSite, rules), fixed };
+  return { site, diagnostics: await runChecks(site, rules), fixed };
 };

package/src/validate/files.ts

@@ -6,10 +6,15 @@ import {
   listContentFiles,
 } from '@mintlify/prebuild';
 import type { Root } from 'mdast';
-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';
 import type {
   Diagnostic,
@@ -22,22 +27,6 @@ import type {
   SiteFile,
 } from './types.js';
 
-const CONCURRENCY = 16;
-
-const mapLimit = async <T, R>(items: T[], task: (item: T) => Promise<R>): Promise<R[]> => {
-  const results = new Array<R>(items.length);
-  let next = 0;
-  await Promise.all(
-    Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
-      while (next < items.length) {
-        const index = next++;
-        results[index] = await task(items[index] as T);
-      }
-    })
-  );
-  return results;
-};
-
 const CHECKED_CATEGORIES = new Set<string | null>(['page', 'snippet', 'snippet-v2']);
 
 export const readSiteFiles = async (baseDir: string): Promise<SiteFile[]> => {
@@ -80,6 +69,8 @@ export const toParseError = (error: unknown): ParseError => {
   };
 };
 
+type Extras = Pick<FileContext, 'readFile' | 'anchorLinks'>;
+
 const parseErrorDiagnostic = (file: string, error: ParseError): Diagnostic => ({
   ...error,
   rule: PARSE_ERROR.id,
@@ -99,8 +90,13 @@ const tryParseContent = (content: string): Root | undefined => {
   }
 };
 
-export const parseFile = (file: string, content: string, baseDir: string): Parsed => {
-  const context = { file, content, baseDir, frontmatter: readFrontmatter(content) };
+export const parseFile = (
+  file: string,
+  content: string,
+  baseDir: string,
+  extras: Extras = {}
+): Parsed => {
+  const context = { file, content, baseDir, frontmatter: readFrontmatter(content), ...extras };
   const tree = tryParseContent(content);
   if (tree) return { context: { ...context, tree }, approximate: false };
   try {
@@ -152,6 +148,7 @@ const checkFile = (
   { file, kind }: SiteFile,
   content: string,
   baseDir: string,
+  extras: Extras,
   variables?: Record<string, string>
 ): Diagnostic[] => {
   const rules = kind === 'snippet' ? allRules.filter((rule) => !rule.pagesOnly) : allRules;
@@ -177,7 +174,7 @@ const checkFile = (
     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, {
@@ -196,17 +193,30 @@ const checkFile = (
   return diagnostics;
 };
 
+const collectSiteAnchorLinks = async (site: Site): Promise<ReadonlySet<string>> => {
+  const pages = await Promise.all(
+    site.files.map(({ file }) => collectAnchorLinks(file, site.read(file) ?? ''))
+  );
+  return new Set(pages.flat());
+};
+
 export const checkFiles = async (site: Site, rules: FileRule[]): Promise<Diagnostic[]> => {
+  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 = await mapLimit(targets, async (entry) => {
-    let content: string;
-    try {
-      content = await fs.readFile(path.join(site.baseDir, entry.file), 'utf-8');
-    } catch (error) {
-      const message = error instanceof Error ? error.message : 'could not read this file';
-      return [parseErrorDiagnostic(entry.file, { message })];
+  const checkTarget = (entry: SiteFile, extras: Extras) => {
+    const content = site.read(entry.file);
+    if (content === undefined) {
+      return [parseErrorDiagnostic(entry.file, { message: 'could not read this file' })];
     }
-    return checkFile(rules, entry, content, site.baseDir, site.variables);
+    return checkFile(rules, entry, content, site.baseDir, extras, site.variables);
+  };
+  const needsLinks = (diagnostics: Diagnostic[]) =>
+    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: await collectSiteAnchorLinks(site) };
+  return targets.flatMap((entry, index) => {
+    const diagnostics = checked[index] ?? [];
+    return needsLinks(diagnostics) ? checkTarget(entry, extras) : diagnostics;
   });
-  return results.flat();
 };

package/src/validate/mdx.ts

@@ -4,7 +4,12 @@ import {
   getCodeRanges,
   HEADING_ID_RE,
   JSXParser,
+  pagePathToSlug,
+  replaceSlashIndex,
+  safeCleanHeadingId,
+  toPosixPath,
 } from '@mintlify/common';
+import { decorateGraphNodeFromPageContent, Node, PathType } from '@mintlify/link-rot';
 import type { Root } from 'mdast';
 
 import type { Edit } from './types.js';
@@ -250,3 +255,36 @@ export const relocate = (
   const mapped = toPosition(original.content, offset);
   return position.column === undefined ? { line: mapped.line } : mapped;
 };
+
+const pagePath = (file: string) => replaceSlashIndex(pagePathToSlug(file)).replace(/^\.$/, '');
+
+export const collectAnchorLinks = async (file: string, content: string): Promise<string[]> => {
+  const node = new Node(file);
+  try {
+    await decorateGraphNodeFromPageContent(node, content);
+  } catch {
+    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: ReadonlySet<string> | undefined,
+  file: string,
+  slug: string
+): string | undefined => {
+  const prefix = `${pagePath(file)}#`;
+  for (const link of 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/src/validate/rules/build.ts

@@ -27,25 +27,39 @@ const POSITION = /^:(\d+)(?::(\d+))?/;
 
 const QUOTED = /"([^"]+)"/;
 
-const toFinding = (site: Site, { type, message }: Warning): Finding => {
-  const clean = stripVTControlCharacters(message).trim();
-  const importer = IMPORT_TYPES.has(type)
-    ? IMPORTERS.map((pattern) => pattern.exec(clean)?.[1]).find(Boolean)
-    : undefined;
+const toFinding = (site: Site, warning: Warning): Finding => {
+  const clean = stripVTControlCharacters(warning.message).trim();
+  const importer =
+    warning.file == null && IMPORT_TYPES.has(warning.type)
+      ? IMPORTERS.map((pattern) => pattern.exec(clean)?.[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 ?? match?.[0];
-  const file = found ? normalizeRelativePath(toPosixPath(found)) : site.configFile;
+  const file =
+    warning.file ?? (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 ? QUOTED.exec(clean)?.[0] : undefined;
+  const quoted =
+    warning.file == null && file === site.configFile ? QUOTED.exec(clean)?.[0] : undefined;
+  const located =
+    warning.ref != null && warning.line == null
+      ? site.locate(file, JSON.stringify(warning.ref))
+      : quoted
+        ? site.locate(file, quoted)
+        : undefined;
   return {
     file,
-    ...(position && {
-      line: Number(position[1]),
-      ...(position[2] && { column: Number(position[2]) }),
-    }),
-    ...(quoted && site.locate(file, quoted)),
+    ...(warning.line != null
+      ? { line: warning.line, ...(warning.column != null && { column: warning.column }) }
+      : position && {
+          line: Number(position[1]),
+          ...(position[2] && { column: Number(position[2]) }),
+        }),
+    ...located,
     message: clean,
   };
 };

package/src/validate/rules/content/duplicateH1.ts

@@ -0,0 +1,78 @@
+import {
+  AVOIDED_PAGE_MODES,
+  getTableOfContentsTitle,
+  safeCleanHeadingId,
+  slugify,
+} from '@mintlify/common';
+import type { Heading, Root } from 'mdast';
+import remarkSmartypants from 'remark-smartypants';
+import { unified } from 'unified';
+
+import { hasCustomHeadingId, linkedAnchor } from '../../mdx.js';
+import type { FileRule } from '../../types.js';
+
+const normalize = (value: string) => value.trim().replace(/\s+/g, ' ');
+
+const smartypants = unified().use(remarkSmartypants);
+
+const firstHeading = (tree: Root) =>
+  tree.children.find((node): node is Heading => node.type === 'heading');
+
+const renderedText = (heading: Heading) => {
+  const clone = structuredClone(heading);
+  const root: Root = { type: 'root', children: [clone] };
+  smartypants.runSync(root);
+  return getTableOfContentsTitle(clone);
+};
+
+export const duplicateH1: FileRule = {
+  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 }) => {
+    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 = first.position?.start.offset ?? 0;
+    const end = first.position?.end.offset ?? start;
+    const location = {
+      line: first.position?.start.line,
+      column: first.position?.start.column,
+    };
+    const lineEnd = content.indexOf('\n', start);
+    if (hasCustomHeadingId(content.slice(start, lineEnd === -1 ? undefined : lineEnd))) {
+      return [
+        {
+          ...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 [
+        {
+          ...location,
+          message: `first heading duplicates the frontmatter title; links point to #${anchor}, so remove it by hand and update them`,
+        },
+      ];
+    }
+    const trailing = /^\n*/.exec(content.slice(end))?.[0].length ?? 0;
+    return [
+      {
+        ...location,
+        message: 'first heading duplicates the frontmatter title',
+        edit: { start, end: end + trailing, text: '' },
+      },
+    ];
+  },
+};

package/src/validate/rules/content/foreignSyntax.ts

@@ -0,0 +1,144 @@
+import { maskCode, maskFrontmatter, maskNonMarkup, toPosition } from '../../mdx.js';
+import type { FileRule, FileFinding } from '../../types.js';
+
+type Pattern = {
+  regex: RegExp;
+  scope?: 'prose' | 'links' | 'prose-and-esm' | 'everything';
+  message: (match: RegExpMatchArray) => string;
+};
+
+const CALLOUTS: Record<string, string> = {
+  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: string | undefined) =>
+  CALLOUTS[name?.toLowerCase() ?? ''] ?? 'a callout (<Note>, <Info>, <Tip> or <Warning>)';
+
+const LIQUID_TAGS: Record<string, string> = {
+  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: Pattern[] = [
+  {
+    regex: /\{%-?\s*(?!end)([\w-]+)[^%\n]*?-?%\}/g,
+    message: ([tag, name]) => {
+      const style = name === 'hint' ? /style=["']?(\w+)/.exec(tag)?.[1] : undefined;
+      const target = style
+        ? callout(style)
+        : (LIQUID_TAGS[name ?? ''] ?? '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]) =>
+      `${link} is a ReadMe link, which Mintlify does not support; link to the page path instead, such as /${
+        link?.split(':')[1] ?? ''
+      }`,
+  },
+  {
+    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: FileRule = {
+  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: FileFinding[] = [];
+    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({ ...toPosition(content, start), message: message(match) });
+      }
+    }
+    return issues;
+  },
+};

package/src/validate/rules/content/katex.ts

@@ -0,0 +1,33 @@
+import { isCurrencyMath } from '@mintlify/common';
+import katex from 'katex';
+import { visit } from 'unist-util-visit';
+
+import type { FileRule, FileFinding } from '../../types.js';
+
+export const katexRule: FileRule = {
+  id: 'katex',
+  group: 'content',
+  severity: 'warning',
+  scope: 'file',
+  description: "math that KaTeX can't render",
+  check: ({ tree, content }) => {
+    const issues: FileFinding[] = [];
+    visit(tree, (node) => {
+      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: node.position?.start.line,
+          column: node.position?.start.column,
+          message: error instanceof Error ? error.message : 'invalid math',
+        });
+      }
+    });
+    return issues;
+  },
+};