@mui/internal-docs-infra/pipeline/transformMarkdownMetadata/types.d.mts

MUI Infra - internal documentation creation tools.

import type { PhrasingContent } from 'mdast';
import { type Audience } from "../../createSitemap/types.mjs";
/**
 * Base options for syncing page indexes.
 * Shared between extractToIndex (markdown metadata) and updateParentIndex (types).
 */
export type SyncPageIndexBaseOptions = {
  /**
   * Base directory for resolving paths.
   * For extractToIndex: directory to strip from file paths before matching.
   * For updateParentIndex: directory to stop recursion at when updating parent indexes.
   */
  baseDir?: string;
  /**
   * Only update existing indexes, don't create new ones.
   * @default false for extractToIndex, true for updateParentIndex
   */
  onlyUpdateIndexes?: boolean;
  /**
   * Directory to write marker files when indexes are updated.
   * Path is relative to baseDir.
   * @default undefined (disabled)
   */
  markerDir?: string;
  /**
   * Throw an error if the index is out of date or missing.
   * Useful for CI environments to ensure indexes are committed.
   * @default false
   */
  errorIfOutOfDate?: boolean;
};
/**
 * Plugin options for transformMarkdownMetadata
 */
export interface TransformMarkdownMetadataOptions {
  /**
   * A suffix to append to the title when saving it to the `export const metadata` object.
   * This suffix is not included in the metadata used for index extraction or returned metadata.
   *
   * Useful for adding site-wide title suffixes like " | My Site" to page metadata.
   *
   * @example
   * ```ts
   * transformMarkdownMetadata({ titleSuffix: ' | Base UI' })
   * // Title "Button" becomes "Button | Base UI" in the export
   * ```
   */
  titleSuffix?: string;
  /**
   * Controls automatic extraction of page metadata to parent directory index files.
   *
   * When enabled, the plugin extracts metadata (title, description, headings) from MDX files
   * and maintains 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/'], exclude: [] }`
   * - `{ include: string[], exclude: string[] }` - Enabled with custom path filters
   *
   * Path matching uses prefix matching - a file matches if it starts with any include path
   * and doesn't start with any exclude path. Files that are index files themselves
   * (matching pattern/page.mdx) are automatically skipped.
   */
  extractToIndex?: boolean | (SyncPageIndexBaseOptions & {
    /** Path prefixes that files must match to have metadata extracted */
    include: string[];
    /** Path prefixes to exclude from metadata extraction */
    exclude: string[];
    /**
     * Directory to write marker files when indexes are updated.
     * Path is relative to baseDir.
     * Set to false to disable marker file creation.
     * Overrides the base type to allow false.
     * @default false
     */
    markerDir?: string | false;
    /**
     * Use the first visible paragraph as the description in the extracted index,
     * even if a meta tag description is present.
     * This does not affect the `export const metadata` which will still use the meta tag.
     * @default false
     */
    useVisibleDescription?: boolean;
    /**
     * Name of a React component to wrap around the autogenerated index content.
     * If provided, the generated markdown will wrap the page list and detail sections
     * in this component (e.g., `<PagesIndex>...</PagesIndex>`).
     *
     * When processing autogenerated index files, the plugin will also automatically
     * inject `SitemapSectionData` as a `data` prop to this wrapper component,
     * enabling dynamic rendering, search, or navigation features.
     *
     * @example 'PagesIndex'
     */
    indexWrapperComponent?: string;
  });
}
/**
 * Represents a hierarchical structure of headings.
 * Each heading is keyed by its slug, with title and nested children.
 */
export type HeadingHierarchy = {
  [slug: string]: {
    title: string;
    titleMarkdown: PhrasingContent[];
    children: HeadingHierarchy;
  };
};
/**
 * Extracted metadata from markdown/MDX files
 */
export interface ExtractedMetadata {
  title?: string;
  description?: string;
  descriptionMarkdown?: PhrasingContent[];
  keywords?: string[];
  sections?: HeadingHierarchy;
  embeddings?: number[];
  image?: {
    url: string;
    alt?: string;
  };
  robots?: {
    index?: boolean;
  };
  other?: {
    audience?: Audience;
    [key: string]: unknown;
  };
}