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

MUI Infra - internal documentation creation tools.

import type { Root } from 'mdast';
import type { ExtractedMetadata } from "../transformMarkdownMetadata/types.mjs";
import { type Audience } from "../../createSitemap/types.mjs";
export interface PageMetadata extends ExtractedMetadata {
  /** The slug/path for this page (e.g., 'button', 'checkbox') */
  slug: string;
  /** The relative path to the page's MDX file */
  path: string;
  /**
   * User-customized display title for the page.
   * When set, this overrides `title` in the navigation list and sitemap.
   * The `title` field continues to be used for the heading section.
   *
   * This value is detected automatically: if a user edits the list item text
   * so it no longer matches the heading, the edited text is preserved here.
   */
  displayTitle?: string;
  /** Tags for this entry (e.g., 'New', 'Hot', 'Beta') */
  tags?: string[];
  /** Skip generating detail section for this entry (for external links) */
  skipDetailSection?: boolean;
  /**
   * The intended audience for this page.
   * When omitted, the page is public and intended for all audiences.
   */
  audience?: Audience;
  /** Whether this page is an index page (has the autogenerated comment marker) */
  index?: boolean;
  /** Component parts with their API metadata (for multi-part components) */
  parts?: Record<string, {
    props?: string[];
    dataAttributes?: string[];
    cssVariables?: string[];
    /** For hooks and functions: parameter names.
     * Each element is a string (positional param) or string[] (object param keys). */
    parameters?: (string | string[])[];
    /** For hooks and functions: return value keys (if returns an object) */
    returns?: string[];
  }>;
  /** Component exports with their API metadata (used for both single and multi-part components) */
  exports?: Record<string, {
    /** For components: prop names */
    props?: string[];
    /** For components: data attribute names */
    dataAttributes?: string[];
    /** For components: CSS variable names */
    cssVariables?: string[];
    /** For hooks and functions: parameter names.
     * Each element is a string (positional param) or string[] (object param keys). */
    parameters?: (string | string[])[];
    /** For hooks and functions: return value keys (if returns an object) */
    returns?: string[];
  }>;
  /** Type names documented on this page (state objects, enums, type aliases, etc.) */
  types?: string[];
}
export interface PagesMetadata {
  /** The main title for the pages index */
  title: string;
  /** Description below the title (editable, persisted) */
  description?: string;
  /** Array of page metadata */
  pages: PageMetadata[];
  /** Page-level metadata for export (e.g., robots, etc.) */
  pageMetadata?: Record<string, unknown>;
  /** Name of a React component that wraps the autogenerated index content */
  indexWrapperComponent?: string;
}
/**
 * Options for metadataToMarkdown and metadataToMarkdownAst functions
 */
export interface MetadataToMarkdownOptions {
  /**
   * Custom editable section marker comment.
   * If not provided, uses the default marker.
   */
  editableMarker?: string;
  /**
   * 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>`).
   * @example 'PagesIndex'
   */
  indexWrapperComponent?: string;
  /**
   * The path to the file being generated. Used in autogenerated comments to help
   * users validate the file.
   */
  path?: string;
}
export declare function metadataToMarkdownAst(data: PagesMetadata, options?: MetadataToMarkdownOptions): Root;
/**
 * Converts an array of page metadata into the markdown format (string)
 */
export declare function metadataToMarkdown(data: PagesMetadata, options?: MetadataToMarkdownOptions | string): string;
/**
 * Parses markdown content and extracts page metadata using unified
 */
export declare function markdownToMetadata(markdown: string): Promise<PagesMetadata | null>;