@mui/internal-docs-infra/withDocsInfra/withDocsInfra.d.mts

MUI Infra - internal documentation creation tools.

import type { NextConfig } from 'next';
import type { RuleSetRule } from 'webpack';
import type { OrderingConfig } from "../pipeline/loadServerTypesText/order.mjs";
import type { DescriptionReplacement } from "../pipeline/loadServerTypesMeta/format.mjs";
import type { EnhanceCodeEmphasisOptions } from "../pipeline/parseSource/calculateFrameRanges.mjs";
import type { TransformHtmlCodeBlockOptions } from "../pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.mjs";
export interface WebpackOptions {
  buildId: string;
  dev: boolean;
  isServer: boolean;
  nextRuntime?: 'nodejs' | 'edge';
  config: NextConfig;
  defaultLoaders: {
    babel: RuleSetRule;
  };
}
export interface WithDocsInfraOptions {
  /**
   * Additional page extensions to support beyond the default docs-infra extensions.
   * Default docs-infra extensions are: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx']
   */
  additionalPageExtensions?: string[];
  /**
   * Whether to enable the export output mode.
   * @default true
   */
  enableExportOutput?: boolean;
  /**
   * Custom demo path pattern for loader rules.
   * @default './app/ ** /demos/ * /index.ts'
   */
  demoPathPattern?: string;
  /**
   * Custom demo path pattern for loader rules.
   * @default './demo-data/ * /index.ts'
   */
  demoDataPathPattern?: string;
  /**
   * Custom client demo path pattern for loader rules.
   * @default './app/ ** /demos/ * /client.ts'
   */
  clientDemoPathPattern?: string;
  /**
   * Additional demo loader patterns for both Turbopack and Webpack.
   * Each pattern will use the appropriate code highlighter loaders.
   */
  additionalDemoPatterns?: {
    /** Patterns for index files that should use loadPrecomputedCodeHighlighter */
    index?: string[];
    /** Patterns for client files that should use loadPrecomputedCodeHighlighterClient */
    client?: string[];
  };
  /**
   * Additional Turbopack rules to merge with the default docs-infra rules.
   */
  additionalTurbopackRules?: Record<string, {
    loaders: string[];
  }>;
  /**
   * When set, `pnpm docs-infra validate` ensures every demo `index.ts` matched by a
   * `loadPrecomputedCodeHighlighter` demo rule has a sibling `client.ts` that imports
   * `createDemoClient` from this path, and that the demo's `create*` factory call
   * receives a `ClientProvider` entry in its meta object.
   *
   * Bare specifiers (e.g. `'@/functions/createDemoClient'`) are written into the
   * generated `client.ts` verbatim. Relative specifiers (e.g. `'./createDemoClient'`,
   * `'../createDemoClient'`) are resolved against the directory containing
   * `next.config.{js,mjs,ts}` and rewritten to be relative to each generated
   * `client.ts` so the same module is imported regardless of demo depth.
   *
   * Existing `client.ts` files are never overwritten.
   */
  requireDemoClient?: string;
  /**
   * When `true`, `pnpm docs-infra validate` ensures every demo `index.ts` matched by a
   * `loadPrecomputedCodeHighlighter` demo rule has a sibling `page.tsx` that renders
   * the demo as the route's default export, so each demo is browsable on its own page.
   *
   * The demo's export name is read from the `create*` factory call in `index.ts`, so the
   * generated page imports the exact export (e.g. `import { DemoButton } from '.';`).
   *
   * Existing `page.tsx`/`page.ts` files are never overwritten.
   */
  requireDemoPage?: boolean;
  /**
   * Performance logging options
   */
  performance?: {
    logging: boolean;
    notableMs?: number;
    showWrapperMeasures?: boolean;
  };
  /**
   * Defer AST parsing option for code highlighter output.
   * 'gzip' - Default, outputs gzipped HAST for best performance.
   * 'json' - Outputs JSON HAST, requires client-side parsing.
   * 'none' - Outputs raw HAST, requires client-side parsing and is largest size.
   * @default 'gzip'
   */
  deferCodeParsing?: 'gzip' | 'json' | 'none';
  /**
   * Prefixes for comments that should be stripped from the source output.
   * Comments starting with these prefixes will be removed from the returned source.
   * They can still be collected via `notableCommentsPrefix`.
   * @example ['@highlight', '@internal']
   */
  removeCommentsWithPrefix?: string[];
  /**
   * Prefixes for notable comments that should be collected and included in the result.
   * Comments starting with these prefixes will be returned in the `comments` field,
   * which can be used by sourceEnhancers to modify the highlighted output.
   * @example ['@highlight', '@focus']
   */
  notableCommentsPrefix?: string[];
  /**
   * Options for the code emphasis enhancer used by demo loaders.
   * Passed to `createEnhanceCodeEmphasis` in the precomputed code highlighter loader.
   */
  demoEmphasisOptions?: EnhanceCodeEmphasisOptions;
  /**
   * Options for code blocks rendered inside generated type metadata.
   * Passed to `transformHtmlCodeBlock` through the types loader pipeline.
   */
  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
  /**
   * When `true`, the demo loaders register the `TypescriptToJavascriptTransformer`
   * so that TypeScript variants also produce a JavaScript counterpart at build time.
   *
   * Defaults to `false` because the transform is comparatively expensive;
   * enable it when the rendered demos should expose both TS and JS sources.
   */
  transformTypescriptToJavascript?: boolean;
  /**
   * Name of the index file to update when syncing types metadata to parent indexes.
   * The types loader will call syncPageIndex to update the parent directory's index
   * with props, dataAttributes, and cssVariables extracted from component types.
   * @default 'page.mdx'
   */
  typesIndexFileName?: string;
  /**
   * Throw an error if any types index is out of date or missing.
   * Useful for CI environments to ensure indexes are committed.
   * @default Boolean(process.env.CI)
   */
  errorIfTypesIndexOutOfDate?: boolean;
  /**
   * Custom ordering configuration for sorting props, data attributes, component exports,
   * namespace parts, and type suffixes in generated documentation.
   *
   * Each array defines the order in which items should appear. Items not in the array
   * are placed at the position of the `__EVERYTHING_ELSE__` marker, sorted alphabetically.
   *
   * All fields are optional — unspecified fields use the built-in defaults.
   */
  ordering?: OrderingConfig;
  /**
   * Pattern/replacement pairs to apply to JSDoc descriptions during type extraction.
   * Each entry has a `pattern` (regex string) and `replacement` string.
   *
   * @example
   * ```js
   * [
   *   { pattern: '\\n\\nDocumentation: .*$', replacement: '', flags: 'm' },
   * ]
   * ```
   */
  descriptionReplacements?: DescriptionReplacement[];
}
export interface DocsInfraMdxOptions {
  remarkPlugins?: Array<string | [string, ...any[]]>;
  rehypePlugins?: Array<string | [string, ...any[]]>;
  /**
   * Additional remark plugins to add to the default docs-infra plugins
   */
  additionalRemarkPlugins?: Array<string | [string, ...any[]]>;
  /**
   * Additional rehype plugins to add to the default docs-infra plugins
   */
  additionalRehypePlugins?: Array<string | [string, ...any[]]>;
  /**
   * Whether to automatically extract page metadata (title, description, headings) from MDX files
   * and maintain an index in the parent directory's page.mdx file.
   *
   * Index files themselves (e.g., pattern/page.mdx) are automatically excluded from extraction.
   *
   * Can be:
   * - `false` - Disabled
   * - `true` - Enabled with default filter: `{ include: ['app', 'src/app'], exclude: [] }`
   * - `{ include: string[], exclude: string[] }` - Enabled with custom path filters
   *
   * @default true
   */
  extractToIndex?: boolean | {
    /** Path prefixes that files must match to have metadata extracted */
    include: string[];
    /** Path prefixes to exclude from metadata extraction */
    exclude: string[];
  };
  /**
   * Base directory for path filtering. Defaults to process.cwd().
   * Only needed when calling the plugin directly (not via withDocsInfra).
   */
  baseDir?: string;
  /**
   * Throw an error if any index is out of date or missing.
   * Useful for CI environments to ensure indexes are committed.
   *
   * @default false
   */
  errorIfIndexOutOfDate?: boolean;
  /**
   * Default language for inline code syntax highlighting.
   * Set to `false` to disable default highlighting for inline code.
   * @default 'tsx'
   */
  defaultInlineCodeLanguage?: string | false;
  /**
   * Options for authored MDX code blocks processed by `transformHtmlCodeBlock`.
   * Passed to `transformHtmlCodeBlock` in the default rehype plugin list.
   */
  codeBlockEmphasisOptions?: TransformHtmlCodeBlockOptions;
}
/**
 * Get default MDX options for docs-infra
 */
export declare function getDocsInfraMdxOptions(customOptions?: DocsInfraMdxOptions): DocsInfraMdxOptions;
/**
 * Next.js plugin for MUI docs infrastructure.
 * Configures webpack loaders, turbopack rules for docs sites.
 * Use getDocsInfraMdxOptions() with createMDX for MDX integration.
 */
export declare function withDocsInfra(options?: WithDocsInfraOptions): (nextConfig?: NextConfig) => NextConfig;