@mui/internal-docs-infra
Version:
MUI Infra - internal documentation creation tools.
65 lines • 3.16 kB
text/typescript
import { type MetadataToMarkdownOptions, type PagesMetadata } from "./metadataToMarkdown.mjs";
/**
* Options for mergeMetadataMarkdown
*/
export interface MergeMetadataMarkdownOptions extends Omit<MetadataToMarkdownOptions, 'editableMarker' | 'indexWrapperComponent'> {
/** If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed. */
preserveUnlisted?: boolean;
/**
* Component name to wrap the autogenerated content.
* - `undefined`: preserve existing wrapper (if any)
* - `null`: explicitly remove the wrapper
* - `string`: use this component name
*/
indexWrapperComponent?: string | null;
/**
* The path to the file being generated. Used in autogenerated comments to help
* users validate the file.
*/
path?: 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 (new metadata takes precedence)
*/
preserveExistingTitleAndSlug?: boolean;
}
/**
* Merges new page metadata with existing markdown content, preserving the order
* of pages from the existing markdown when available, unless the file contains
* only the autogeneration marker (no editable section), in which case pages are
* sorted alphabetically by title.
*
* Pages are matched by their `path` property (e.g., './button/page.mdx'), not by slug.
* This allows multiple pages to have the same slug (anchor) while still being treated
* as distinct pages.
*
* @param existingMarkdown - The existing markdown content (or undefined if none exists)
* @param newMetadata - The new metadata to merge in
* @param options - Optional configuration
* @param options.preserveUnlisted - If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed.
* @param options.indexWrapperComponent - Optional component name to wrap the autogenerated content (e.g., 'PagesIndex')
* @returns The updated markdown content with merged metadata
*
* @example
* ```ts
* const existingMarkdown = `# Components
* - Button - ([Outline](#button), [Contents](./button/page.mdx)) - A button
* - Checkbox - ([Outline](#checkbox), [Contents](./checkbox/page.mdx)) - A checkbox
* `;
*
* const newMetadata = {
* title: 'Components',
* pages: [
* { slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: 'Updated checkbox' },
* { slug: 'button', path: './button/page.mdx', title: 'Button', description: 'Updated button' },
* { slug: 'input', path: './input/page.mdx', title: 'Input', description: 'New input' },
* ],
* };
*
* const result = await mergeMetadataMarkdown(existingMarkdown, newMetadata);
* // Result preserves Button, Checkbox order from existing markdown, adds Input at the end
* ```
*/
export declare function mergeMetadataMarkdown(existingMarkdown: string | undefined, newMetadata: PagesMetadata, options?: MergeMetadataMarkdownOptions): Promise<string>;