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>;