With Docs Infra

The withDocsInfra function is a Next.js configuration plugin that sets up webpack loaders, Turbopack rules, and page extensions required for MUI docs infrastructure. It automatically configures code highlighting loaders for demo files and provides sensible defaults for documentation sites.

Features

Configures webpack and Turbopack loaders for demo files (index.ts and client.ts)
Sets up page extensions to support .md, .mdx, .ts, .tsx, .js, .jsx files
Enables export output mode by default for static site generation
Provides extensible patterns for custom demo file structures
Includes companion getDocsInfraMdxOptions for MDX plugin configuration

Basic Usage

// next.config.mjs
import { withDocsInfra } from '@mui/internal-docs-infra/withDocsInfra';

const nextConfig = {
  // Your existing Next.js config
};

export default withDocsInfra()(nextConfig);

Advanced Configuration

// next.config.mjs
import { withDocsInfra, getDocsInfraMdxOptions } from '@mui/internal-docs-infra/withDocsInfra';
import createMDX from '@next/mdx';

const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    // Control index generation
    extractToIndex: {
      include: ['app/docs', 'app/api'],
      exclude: ['app/docs/internal'],
    },
  }),
});

const nextConfig = {
  // Your Next.js config
};

export default withDocsInfra({
  // Add support for additional file extensions
  additionalPageExtensions: ['vue', 'svelte'],

  // Disable export output if using server features
  enableExportOutput: false,

  // Add custom demo patterns beyond the defaults
  additionalDemoPatterns: {
    index: ['./app/**/demos/*/demo-*/index.ts'],
    client: ['./app/**/demos/*/demo-*/client.ts'],
  },

  // Add custom Turbopack rules
  additionalTurbopackRules: {
    './custom/**/*.ts': {
      loaders: ['custom-loader'],
    },
  },
})(withMDX(nextConfig));

Default Configurations

Page Extensions

By default, withDocsInfra enables these page extensions:

js, jsx - JavaScript files
md, mdx - Markdown files
ts, tsx - TypeScript files

Demo File Patterns

The plugin automatically configures loaders for these patterns:

Turbopack Rules:

{
  './app/**/demos/*/index.ts': {
    loaders: ['@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter']
  },
  './app/**/demos/*/client.ts': {
    loaders: ['@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighterClient']
  }
}

Webpack Rules:

{
  test: /[/\\]demos[/\\][^/\\]+[/\\]index\.ts$/,
  use: [
    defaultLoaders.babel,
    '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter'
  ]
}

MDX Integration

Use getDocsInfraMdxOptions to configure MDX with docs-infra plugins:

import { withDocsInfra, getDocsInfraMdxOptions } from '@mui/internal-docs-infra/withDocsInfra';
import createMDX from '@next/mdx';

// Default docs-infra MDX plugins with automatic index generation
const withMDX = createMDX({
  options: getDocsInfraMdxOptions(),
});

const nextConfig = {
  // Your Next.js config
};

export default withDocsInfra()(withMDX(nextConfig));

// With additional plugins
const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    additionalRemarkPlugins: [['remark-emoji']],
    additionalRehypePlugins: [['rehype-highlight']],
  }),
});

// Custom plugin overrides (replaces all default plugins)
const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    remarkPlugins: [['remark-gfm'], ['custom-plugin']],
    rehypePlugins: [['custom-rehype-plugin']],
  }),
});

Controlling Index Generation

The extractToIndex option is passed via getDocsInfraMdxOptions, not withDocsInfra:

// Disable index generation
const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    extractToIndex: false,
  }),
});

export default withDocsInfra()(withMDX(nextConfig));

// Custom path filters for index generation
const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    extractToIndex: {
      include: ['app/docs', 'app/api'],
      exclude: ['app/docs/internal'],
    },
  }),
});

export default withDocsInfra()(withMDX(nextConfig));

Default MDX Plugins

Remark Plugins (Markdown processing)

remark-gfm - GitHub Flavored Markdown support
transformMarkdownRelativePaths - Convert relative paths for docs
transformMarkdownBlockquoteCallouts - Convert blockquotes to callouts
transformMarkdownCode - Process code blocks

Rehype Plugins (HTML processing)

transformHtmlCode - Transform HTML code elements

Configuration Options

WithDocsInfraOptions

Option	Type	Default	Description
`additionalPageExtensions`	`string[]`	`[]`	Additional file extensions to treat as pages
`enableExportOutput`	`boolean`	`true`	Enable Next.js export output mode
`demoPathPattern`	`string`	`'./app/*/demos//index.ts'`	Pattern for demo index files
`clientDemoPathPattern`	`string`	`'./app/*/demos//client.ts'`	Pattern for demo client files
`additionalDemoPatterns`	`object`	`{}`	Additional demo patterns for custom structures
`additionalTurbopackRules`	`object`	`{}`	Custom Turbopack loader rules

DocsInfraMdxOptions

Option	Type	Default	Description
`remarkPlugins`	`Array`	See Default MDX Plugins	Override default remark plugins completely
`rehypePlugins`	`Array`	See Default MDX Plugins	Override default rehype plugins completely
`additionalRemarkPlugins`	`Array`	`[]`	Add plugins to default remark plugins
`additionalRehypePlugins`	`Array`	`[]`	Add plugins to default rehype plugins
`extractToIndex`	`boolean \| { include: string[], exclude: string[] }`	`true` (with default filter)	Control metadata extraction to parent index files (see Automatic Index Generation)
`baseDir`	`string`	`process.cwd()`	Base directory for path filtering (auto-detected, rarely needs manual configuration)

Example: Custom Demo Structure

If your demos follow a different pattern (e.g., demo-variant/index.ts):

const nextConfig = withDocsInfra({
  additionalDemoPatterns: {
    index: ['./app/**/demos/*/demo-*/index.ts'],
    client: ['./app/**/demos/*/demo-*/client.ts'],
  },
})({});

This will configure loaders for paths like:

./app/components/demos/Button/demo-variant/index.ts
./app/components/demos/Button/demo-basic/client.ts

How It Works

Page Extensions: Configures Next.js to recognize additional file types as pages
Export Output: Enables static export mode for documentation sites
Turbopack Rules: Sets up fast refresh and bundling for demo files in development
Webpack Rules: Configures production bundling with appropriate loaders
Pattern Conversion: Converts glob patterns to webpack regex for file matching

Integration Example

Complete Next.js configuration for a docs site:

// next.config.mjs
import { withDocsInfra, getDocsInfraMdxOptions } from '@mui/internal-docs-infra/withDocsInfra';
import createMDX from '@next/mdx';

const withMDX = createMDX({
  options: getDocsInfraMdxOptions({
    additionalRemarkPlugins: [['remark-emoji']],
  }),
});

const nextConfig = {
  // Your app-specific config
  experimental: {
    appDir: true,
  },
};

export default withDocsInfra({
  additionalDemoPatterns: {
    index: ['./app/**/demos/*/demo-*/index.ts'],
    client: ['./app/**/demos/*/demo-*/client.ts'],
  },
})(withMDX(nextConfig));

Automatic Index Generation

By default, the plugin automatically extracts page metadata and maintains parent directory indexes. See examples in Controlling Index Generation above.

The default filter { include: ['app', 'src/app'], exclude: [] } processes all pages in both app/ and src/app/ directories (without trailing slashes - they're added automatically during matching). Index files (e.g., app/page.mdx, app/components/page.mdx) are automatically excluded to prevent them from creating parent indexes. The base directory is automatically detected from process.cwd().

For complete details, see the transformMarkdownMetadata documentation.

When to Use

Required for any Next.js app using MUI docs-infra components
When building documentation sites with live demos
When you need automatic code highlighting for demo files
When using MDX with docs-infra markdown transformations

loadPrecomputedCodeHighlighter - Loader for demo index files
loadPrecomputedCodeHighlighterClient - Loader for demo client files
CodeHighlighter - Component that renders highlighted demos