@mui/internal-docs-infra/pipeline/syncPageIndex/syncPageIndex.d.mts

MUI Infra - internal documentation creation tools.

import * as lockfile from 'proper-lockfile';
import type { PageMetadata } from "./metadataToMarkdown.mjs";
export interface SyncPageIndexOptions {
  /**
   * The path to the page file (e.g., './app/components/button/page.mdx')
   * OR the path to the index file itself when using metadataList
   */
  pagePath: string;
  /**
   * The metadata extracted from the page
   * Either provide this for a single update, or metadataList for batch updates
   */
  metadata?: PageMetadata;
  /**
   * Array of metadata for batch updates
   * When provided, all metadata will be merged in a single file lock/write operation
   */
  metadataList?: PageMetadata[];
  /**
   * The title for the index file (e.g., 'Components')
   * If not provided, will be derived from the parent directory name
   * (e.g., 'app/components/page.mdx' -> 'Components')
   */
  indexTitle?: string;
  /**
   * The name of the index file to update (e.g., 'page.mdx')
   * Defaults to 'page.mdx'
   */
  indexFileName?: string;
  /**
   * Lock options for proper-lockfile
   */
  lockOptions?: lockfile.LockOptions;
  /**
   * The base directory to stop recursion at (e.g., './app')
   * If not provided, will continue until reaching the root directory
   */
  baseDir?: string;
  /**
   * Whether to update parent indexes recursively
   * @default false
   */
  updateParents?: boolean;
  /**
   * Path patterns to include when creating/updating indexes
   * Only indexes within these paths will be created or modified
   * Patterns are matched against the directory path relative to baseDir
   */
  include?: string[];
  /**
   * Path patterns to exclude when creating/updating indexes
   * Indexes matching these patterns will not be created or modified
   * Patterns are matched against the directory path relative to baseDir
   */
  exclude?: string[];
  /**
   * Only update existing indexes, don't create new ones
   * When true, will skip updating if the index file doesn't already exist
   * @default false
   */
  onlyUpdateIndexes?: boolean;
  /**
   * Directory to write marker files when indexes are updated.
   * Path is relative to baseDir.
   * Set to false to disable marker file creation.
   * A marker file will be created at: `${markerDir}/${relativePath}/page.mdx`
   * @default false
   */
  markerDir?: string | false;
  /**
   * 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;
  /**
   * Optional component name to wrap the autogenerated index content.
   * When provided, the content will be wrapped like: `<ComponentName>...</ComponentName>`
   * @example 'PagesIndex'
   */
  indexWrapperComponent?: string;
  /**
   * If true, preserve existing page titles and slugs when they exist.
   * New metadata titles/slugs will only be used if the existing page doesn't have them.
   * Useful when auto-generating metadata that shouldn't override user-set values.
   * @default false
   */
  preserveExistingTitleAndSlug?: boolean;
}
/**
 * Updates the parent directory's index file with metadata from a page.
 *
 * This function:
 * 1. Acquires a lock on the index file
 * 2. Reads the existing index markdown (if it exists)
 * 3. Merges the new page metadata with existing metadata
 * 4. Writes the updated markdown back to the index file
 * 5. Releases the lock
 * 6. Optionally updates parent indexes recursively
 *
 * @example
 * ```ts
 * await syncPageIndex({
 *   pagePath: './app/components/button/page.mdx',
 *   metadata: {
 *     slug: 'button',
 *     path: './button/page.mdx',
 *     title: 'Button',
 *     description: 'A button component.',
 *   },
 *   indexTitle: 'Components',
 * });
 * ```
 */
export declare function syncPageIndex(options: SyncPageIndexOptions): Promise<void>;