Configuration API

/**
 * Creates a typed VitePress configuration object with default theme support
 * @param config - VitePress configuration with DefaultTheme.Config
 * @returns The same config object (identity function for type inference)
 */
function defineConfig(config: UserConfig<DefaultTheme.Config>): UserConfig<DefaultTheme.Config>;

import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Site",
  description: "A documentation site built with VitePress",
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" }
    ],
    sidebar: {
      "/guide/": [
        {
          text: "Getting Started",
          items: [
            { text: "Introduction", link: "/guide/introduction" },
            { text: "Setup", link: "/guide/setup" }
          ]
        }
      ]
    }
  }
});

/**
 * Creates a typed VitePress configuration object with custom theme support
 * @param config - VitePress configuration with generic ThemeConfig type
 * @returns The same config object (identity function for type inference)
 */
function defineConfigWithTheme<ThemeConfig>(
  config: UserConfig<ThemeConfig>
): UserConfig<ThemeConfig>;

import { defineConfigWithTheme } from "vitepress";

interface CustomTheme {
  primaryColor: string;
  customNavbar: boolean;
}

export default defineConfigWithTheme<CustomTheme>({
  title: "Custom Theme Site",
  themeConfig: {
    primaryColor: "#3eaf7c",
    customNavbar: true
  }
});

/**
 * Resolves and normalizes VitePress configuration
 * @param root - Project root directory (defaults to process.cwd())
 * @param command - Build command type (defaults to 'serve')
 * @param mode - Development mode string (defaults to 'development')
 * @returns Promise resolving to fully resolved SiteConfig
 */
function resolveConfig(
  root?: string,
  command?: "serve" | "build",
  mode?: string
): Promise<SiteConfig>;

import { resolveConfig } from "vitepress";

// Resolve configuration for build
const config = await resolveConfig("./docs", "build", "production");
console.log("Resolved site config:", config.site);
console.log("Output directory:", config.outDir);

/**
 * Loads and resolves user configuration from config file
 * @param root - Project root directory
 * @param command - Build command type
 * @param mode - Development mode string
 * @returns Tuple of [userConfig, configPath, configDependencies]
 */
function resolveUserConfig(
  root: string,
  command: "serve" | "build",
  mode: string
): Promise<[UserConfig, string?, string[]]>;

/**
 * Resolves site data from user configuration
 * @param root - Project root directory
 * @param userConfig - User configuration object
 * @param command - Build command type
 * @param mode - Development mode string
 * @returns Promise resolving to SiteData object
 */
function resolveSiteData(
  root: string,
  userConfig?: UserConfig,
  command?: "serve" | "build",
  mode?: string
): Promise<SiteData>;

/**
 * Merges two VitePress configuration objects
 * @param a - First configuration object
 * @param b - Second configuration object (takes priority)
 * @param isRoot - Whether this is a root level merge
 * @returns Merged UserConfig object
 */
function mergeConfig(
  a: UserConfig,
  b: UserConfig,
  isRoot?: boolean
): UserConfig;

import { mergeConfig, defineConfig } from "vitepress";

const baseConfig = defineConfig({
  title: "Base Site",
  themeConfig: {
    nav: [{ text: "Home", link: "/" }]
  }
});

const extendedConfig = defineConfig({
  description: "Extended site description",
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "About", link: "/about" }
    ]
  }
});

const merged = mergeConfig(baseConfig, extendedConfig);

interface UserConfig<ThemeConfig = any> {
  /**
   * Configuration to extend from
   */
  extends?: UserConfig<ThemeConfig>;
  
  /**
   * Base URL path for the site
   * @default '/'
   */
  base?: string;
  
  /**
   * Source directory containing markdown files
   * @default '.'
   */
  srcDir?: string;
  
  /**
   * Output directory for built site
   * @default '.vitepress/dist'
   */
  outDir?: string;
  
  /**
   * Cache directory for temporary files
   * @default '.vitepress/cache'
   */
  cacheDir?: string;
  
  /**
   * Site title
   */
  title?: string;
  
  /**
   * Site title template or boolean to disable
   */
  titleTemplate?: string | boolean;
  
  /**
   * Site description
   */
  description?: string;
  
  /**
   * HTML head tags configuration
   */
  head?: HeadConfig[];
  
  /**
   * Default language for the site
   * @default 'en-US'
   */
  lang?: string;
  
  /**
   * Text direction for the site
   * @default 'ltr'
   */
  dir?: string;
  
  /**
   * Theme-specific configuration
   */
  themeConfig?: ThemeConfig;
  
  /**
   * Markdown processing options
   */
  markdown?: MarkdownOptions;
  
  /**
   * Vite configuration
   */
  vite?: ViteUserConfig;
  
  /**
   * Vue configuration
   */
  vue?: VueOptions;
  
  /**
   * Multi-language configuration
   */
  locales?: LocaleConfig<ThemeConfig>;
  
  /**
   * Dark mode appearance configuration
   * @default true
   */
  appearance?: 
    | boolean 
    | 'dark' 
    | 'force-dark' 
    | 'force-auto'
    | (Omit<UseDarkOptions, 'initialValue'> & { 
        initialValue?: 'dark' 
      });
  
  /**
   * Last updated timestamp feature
   * @default false
   */
  lastUpdated?: boolean;
  
  /**
   * Clean URLs without .html extension
   * @default false
   */
  cleanUrls?: boolean;
  
  /**
   * Enable Multi-Page Application mode
   * @default false
   */
  mpa?: boolean;
  
  /**
   * URL rewrites configuration
   */
  rewrites?: Record<string, string>;
  
  /**
   * Sitemap generation options
   */
  sitemap?: {
    hostname: string;
    transformItems?: (items: SitemapItem[]) => Awaitable<SitemapItem[]>;
  };
  
  /**
   * Meta chunk options for performance
   * @default false
   */
  metaChunk?: boolean;
  
  /**
   * Build concurrency control
   */
  buildConcurrency?: number;
  
  /**
   * Scroll offset for anchor links
   */
  scrollOffset?: 
    | number 
    | string 
    | string[] 
    | { selector: string | string[]; padding: number };
  
  /**
   * Ignore dead links patterns
   */
  ignoreDeadLinks?: 
    | boolean 
    | 'localhostLinks' 
    | (string | RegExp | ((link: string) => boolean))[];
  
  /**
   * Transform functions for build pipeline
   */
  transformHead?: (ctx: TransformContext) => Awaitable<HeadConfig[]>;
  transformHtml?: (code: string, id: string, ctx: TransformContext) => Awaitable<string>;
  transformPageData?: (pageData: PageData, ctx: TransformContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>;
  
  /**
   * Build hooks
   */
  buildEnd?: (siteConfig: SiteConfig) => Awaitable<void>;
  postRender?: (context: SSGContext) => Awaitable<SSGContext | void>;
}

interface SiteConfig<ThemeConfig = any> extends UserConfig<ThemeConfig> {
  /**
   * Resolved project root directory
   */
  root: string;
  
  /**
   * Resolved source directory path
   */
  srcDir: string;
  
  /**
   * Resolved site data
   */
  site: SiteData<ThemeConfig>;
  
  /**
   * Configuration file path
   */
  configPath?: string;
  
  /**
   * Configuration dependencies
   */
  configDeps: string[];
  
  /**
   * Discovered pages
   */
  pages: string[];
  
  /**
   * Dynamic route patterns
   */
  dynamicRoutes: SiteConfig['pages'];
  
  /**
   * Rewrites mapping
   */
  rewrites: SiteConfig['rewrites'];
  
  /**
   * Logger instance
   */
  logger: Logger;
  
  /**
   * Temporary directory path
   */
  tempDir: string;
  
  /**
   * Markdown renderer instance
   */
  markdown: MarkdownRenderer;
}

interface MarkdownOptions {
  /**
   * Show line numbers in code blocks
   * @default false
   */
  lineNumbers?: boolean;
  
  /**
   * Custom MarkdownIt configuration
   */
  config?: (md: MarkdownIt) => void;
  
  /**
   * Syntax highlighting theme
   */
  theme?: 
    | ThemeOptions
    | { light: ThemeOptions; dark: ThemeOptions };
  
  /**
   * Supported programming languages
   */
  languages?: LanguageInput[];
  
  /**
   * Custom anchor options
   */
  anchor?: AnchorOptions;
  
  /**
   * Table of contents options
   */
  toc?: TocOptions;
  
  /**
   * External links attributes
   */
  externalLinks?: Record<string, string>;
  
  /**
   * Enable markdown caching
   * @default true
   */
  cache?: boolean;
  
  /**
   * Math rendering options
   */
  math?: boolean;
  
  /**
   * Image processing options
   */
  image?: {
    lazy?: boolean;
    lazyLoading?: boolean;
  };
  
  /**
   * Container options
   */
  container?: {
    tipLabel?: string;
    warningLabel?: string;
    dangerLabel?: string;
    infoLabel?: string;
    detailsLabel?: string;
  };
}

interface LocaleSpecificConfig<ThemeConfig = any> {
  /**
   * Language code for this locale
   */
  lang?: string;
  
  /**
   * Text direction
   */
  dir?: string;
  
  /**
   * Site title for this locale
   */
  title?: string;
  
  /**
   * Title template for this locale
   */
  titleTemplate?: string | boolean;
  
  /**
   * Site description for this locale
   */
  description?: string;
  
  /**
   * HTML head configuration for this locale
   */
  head?: HeadConfig[];
  
  /**
   * Theme configuration for this locale
   */
  themeConfig?: ThemeConfig;
}

interface TransformContext {
  /**
   * Site configuration
   */
  siteConfig: SiteConfig;
  
  /**
   * Site data
   */
  siteData: SiteData;
  
  /**
   * Current page data
   */
  pageData: PageData;
  
  /**
   * Page title
   */
  title: string;
  
  /**
   * Page description
   */
  description: string;
  
  /**
   * HTML head configuration
   */
  head: HeadConfig[];
  
  /**
   * Current locale index
   */
  localeIndex: string;
  
  /**
   * Content of the page
   */
  content: string;
}

interface SSGContext extends SSRContext {
  /**
   * Rendered content
   */
  content: string;
  
  /**
   * Social icons used in the page
   */
  vpSocialIcons: Set<string>;
}