MUI Docs Infra

Validate

The validate command ensures that committed index files match the expected output. It processes all page.mdx files, extracts metadata, and verifies that parent indexes are up-to-date.

Usage

pnpm docs-infra validate [paths...]

Arguments

ArgumentTypeDescription
pathsstring[]Optional paths to validate (e.g., docs-infra/components)

Options

OptionTypeDefaultDescription
--commandstringpnpm docs-infra validateCommand to suggest when indexes are out of date
--useVisibleDescriptionbooleanfalseUse first visible paragraph as description

Examples

Validate All Indexes

pnpm docs-infra validate

Processes all page.mdx files in src/app/ and app/ directories.

Validate Specific Sections

pnpm docs-infra validate docs-infra/components docs-infra/functions

Only validates indexes under the specified paths.

Use Visible Description

pnpm docs-infra validate --useVisibleDescription

Uses the first visible paragraph in each page as the description, instead of the meta tag.

How It Works

  1. Find Files: Searches for all page.mdx files in the app directories
  2. Process Metadata: Runs each file through the unified pipeline with transformMarkdownMetadata
  3. Check Indexes: Compares generated metadata against existing index files
  4. Report Results: Lists which indexes were updated and their paths
  5. CI Mode: In CI environments, exits with error if any indexes changed

Output

When All Indexes Are Current

Validating committed files match expected output...

Processing 47 page.mdx files...

No indexes needed updating

✓ 0 index files updated in 1.23s

When Indexes Need Updates

Validating committed files match expected output...

Processing 47 page.mdx files...

Updated index files:
  app/docs-infra/components/page.mdx
  app/docs-infra/functions/page.mdx

Total: 2 indexes updated

✓ 2 index files updated in 1.45s

CI Failure

When running in CI (CI=true) and indexes are out of date:

Updated index files:
  app/docs-infra/components/page.mdx

Total: 1 indexes updated

✓ 1 index files updated in 1.23s

✗ Index files are out of date. Run this command locally:

  pnpm docs-infra validate docs-infra/components

Then commit the results.

Exit code: 1

Marker Files

The command uses marker files to track which indexes were updated:

  • Location: .next/cache/docs-infra/index-updates/
  • These files are temporary and cleaned up before each run
  • Used to determine which paths to suggest in CI error messages

Integration with transformMarkdownMetadata

The validate command uses the transformMarkdownMetadata plugin internally:

const processor = unified()
  .use(remarkParse)
  .use(remarkMdx)
  .use(transformMarkdownMetadata, {
    extractToIndex: {
      include: includePatterns,
      exclude: [],
      baseDir: cwd,
      onlyUpdateIndexes: true,
      markerDir: '.next/cache/docs-infra/index-updates',
      useVisibleDescription,
    },
  });

Related