@mintlify/cli 4.0.1742 → 4.0.1744

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/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;
+  },
+};

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

@@ -0,0 +1,130 @@
+import {
+  collectPatternNames,
+  collectExportedNames,
+  getAST,
+  isBuiltInComponent,
+  JSX_EXTENSIONS,
+  visitReferences,
+} from '@mintlify/common';
+import { visit } from 'unist-util-visit';
+
+import type { FileContext, FileRule, FileFinding } from '../../types.js';
+
+const getDeclared = (context: FileContext): Set<string> => {
+  const declared = new Set<string>();
+  visit(context.tree, 'mdxjsEsm', (node) => {
+    for (const statement of node.data?.estree?.body ?? []) {
+      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?.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: FileContext): number => {
+  const frontmatter = context.tree.children.find((child) => ['yaml', 'toml'].includes(child.type));
+  return frontmatter?.position?.end.offset ?? 0;
+};
+
+const getSpecifier = (snippet: string, file: string, name: string): string | undefined => {
+  let exported: Set<string>;
+  try {
+    exported = collectExportedNames(getAST(snippet, file));
+  } catch {
+    return undefined;
+  }
+  if (exported.has(name)) return `{ ${name} }`;
+  return exported.has('default') ? name : undefined;
+};
+
+export const unknownComponent: FileRule = {
+  id: 'unknown-component',
+  group: 'content',
+  severity: 'warning',
+  scope: 'file',
+  description: 'JSX components that are not built in, imported or exported',
+  pagesOnly: true,
+  check: (context) => {
+    const declared = getDeclared(context);
+    const reported = new Set<string>();
+    const issues: FileFinding[] = [];
+    const insertAt = getImportPosition(context);
+    const prefix = insertAt === 0 ? '' : '\n\n';
+    const following = /^\n*/.exec(context.content.slice(insertAt))?.[0].length ?? 0;
+    const suffix = '\n'.repeat(Math.max(0, 2 - following));
+
+    const check = (
+      tag: string | null | undefined,
+      position: { line?: number; column?: number } | undefined
+    ) => {
+      const name = 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) => context.readFile?.(candidate) !== undefined
+      );
+      const source = file && context.readFile?.(file);
+      const specifier =
+        file && source !== undefined && tag === name ? getSpecifier(source, file, name) : undefined;
+      issues.push({
+        line: position?.line,
+        column: 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: unknown, fallback?: { line?: number; column?: number }) =>
+      visitReferences(estree, new Set(), {
+        reference: (identifier) => {
+          if (identifier.type !== 'JSXIdentifier') return;
+          const loc = identifier.loc as { start?: { line: number; column: number } } | undefined;
+          check(String(identifier.name), loc?.start ?? fallback);
+        },
+      });
+
+    visit(context.tree, (node) => {
+      if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+        check(node.name, node.position?.start);
+        for (const attribute of node.attributes) {
+          const value = attribute.type === 'mdxJsxAttribute' ? attribute.value : attribute;
+          if (value && typeof value === 'object') {
+            checkJsxInExpression(value.data?.estree, node.position?.start);
+          }
+        }
+      } else if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+        checkJsxInExpression(node.data?.estree, node.position?.start);
+      }
+    });
+    return issues;
+  },
+};

package/src/validate/rules/index.ts

@@ -1,7 +1,19 @@
 import type { Rule } from '../types.js';
 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: Rule[] = [voidTags, openApiSpec, ...BUILD_RULES];
+export const RULES: Rule[] = [
+  voidTags,
+  duplicateH1,
+  unknownComponent,
+  katexRule,
+  foreignSyntax,
+  openApiSpec,
+  ...BUILD_RULES,
+];

package/src/validate/site.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 
 import { readSiteFiles } from './files.js';
@@ -22,18 +22,18 @@ export const loadSite = async (
   { selected, localSchema }: { selected?: ReadonlySet<string>; localSchema: boolean }
 ): Promise<Site> => {
   const files = await readSiteFiles(baseDir);
-  const byPath = new Map<string, string>();
-  const configFile = existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
+  const byPath = new Map<string, string | undefined>();
+  const configFile = fs.existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
 
   const read = (file: string) => {
     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 {
-        byPath.set(file, '');
+        byPath.set(file, undefined);
       }
     }
-    return byPath.get(file) ?? '';
+    return byPath.get(file);
   };
 
   return {
@@ -41,10 +41,11 @@ export const loadSite = async (
     files,
     selected,
     configFile,
-    variables: readVariables(read(configFile)),
+    variables: readVariables(read(configFile) ?? ''),
     localSchema,
+    read,
     locate: (file, text) => {
-      const content = read(file);
+      const content = read(file) ?? '';
       const offset = text ? content.indexOf(text) : -1;
       return offset === -1 ? {} : toPosition(content, offset);
     },