Types and Configuration

interface SiteConfig {
  /** Site title displayed in the header */
  title?: string;
  
  /** Site description for SEO and meta tags */
  description?: string;
  
  /** Base URL path for deployment (default: "/") */
  base?: string;
  
  /** HTML head tags to inject */
  head?: HeadTag[];
  
  /** Theme-specific configuration */
  themeConfig?: any;
  
  /** Markdown processor configuration */
  markdown?: MarkdownConfig;
  
  /** File patterns to include when scanning for pages */
  patterns?: string[];
  
  /** Default permalink pattern for pages */
  permalink?: string;
  
  /** Locale configuration for internationalization */
  locales?: LocaleConfig;
  
  /** Temporary directory override */
  temp?: string;
  
  /** Build output directory override */
  dest?: string;
  
  /** Plugin configurations */
  plugins?: PluginConfig[];
  
  /** Theme configuration */
  theme?: string | ThemeConfig;
}

const siteConfig = {
  title: "My Documentation",
  description: "Comprehensive guide and API reference",
  base: "/docs/",
  head: [
    ["link", { rel: "icon", href: "/favicon.ico" }],
    ["meta", { name: "theme-color", content: "#3eaf7c" }],
  ],
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" },
      { text: "API", link: "/api/" },
    ],
    sidebar: {
      "/guide/": ["", "installation", "configuration"],
      "/api/": ["", "core", "plugins"],
    },
  },
  markdown: {
    lineNumbers: true,
    extractHeaders: ["h1", "h2", "h3"],
  },
  plugins: [
    ["@vuepress/plugin-search"],
    ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
  ],
};

interface MarkdownConfig {
  /** Show line numbers in code blocks */
  lineNumbers?: boolean;
  
  /** Header levels to extract for navigation */
  extractHeaders?: string[];
  
  /** Markdown-it options */
  options?: any;
  
  /** Custom markdown-it plugins */
  plugins?: any[];
  
  /** Anchor options for headers */
  anchor?: AnchorOptions;
  
  /** Table of contents options */
  toc?: TocOptions;
  
  /** External link options */
  externalLinks?: ExternalLinkOptions;
}

interface AnchorOptions {
  /** Permalink symbol */
  permalink?: boolean;
  /** Permalink symbol position */
  permalinkBefore?: boolean;
  /** Permalink symbol */
  permalinkSymbol?: string;
}

const markdownConfig = {
  lineNumbers: true,
  extractHeaders: ["h1", "h2", "h3", "h4"],
  anchor: {
    permalink: true,
    permalinkBefore: true,
    permalinkSymbol: "#",
  },
  plugins: [
    "markdown-it-footnote",
    ["markdown-it-container", "warning"],
  ],
};

type HeadTag = [string, { [key: string]: string }, string?];

// Format: [tagName, attributes, innerHTML?]

const headTags = [
  // Basic meta tag
  ["meta", { name: "author", content: "John Doe" }],
  
  // Link tag
  ["link", { rel: "stylesheet", href: "/custom.css" }],
  
  // Script tag with content
  ["script", {}, "console.log('Custom script');"],
  
  // Script tag with src
  ["script", { src: "/analytics.js", async: "true" }],
  
  // Favicon
  ["link", { rel: "icon", href: "/favicon.png", type: "image/png" }],
];

interface LocaleConfig {
  [path: string]: LocaleOptions;
}

interface LocaleOptions {
  /** Locale language code */
  lang?: string;
  
  /** Locale title override */
  title?: string;
  
  /** Locale description override */
  description?: string;
  
  /** Locale-specific theme config */
  themeConfig?: any;
}

const locales = {
  "/": {
    lang: "en-US",
    title: "Documentation",
    description: "English documentation",
  },
  "/zh/": {
    lang: "zh-CN",
    title: "文档",
    description: "中文文档",
    themeConfig: {
      nav: [
        { text: "首页", link: "/zh/" },
        { text: "指南", link: "/zh/guide/" },
      ],
    },
  },
  "/es/": {
    lang: "es-ES", 
    title: "Documentación",
    description: "Documentación en español",
  },
};

type PluginConfig = 
  | string                    // Plugin name
  | [string, any]            // Plugin name with options
  | Plugin                   // Plugin object
  | [Plugin, any];           // Plugin object with options

interface Plugin {
  /** Plugin identifier */
  name?: string;
  
  /** Allow multiple instances of this plugin */
  multiple?: boolean;
  
  /** Child plugins to register */
  plugins?: PluginConfig[];
  
  /** Plugin implementation */
  [optionName: string]: any;
}

// Different plugin configuration formats
const pluginConfigs = [
  // String name (uses defaults)
  "@vuepress/plugin-blog",
  
  // String name with options
  ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
  
  // Plugin object
  {
    name: "custom-plugin",
    ready() {
      console.log("Ready!");
    },
  },
  
  // Plugin object with options
  [{
    name: "configurable-plugin",
    ready(config) {
      console.log(`Config: ${JSON.stringify(config)}`);
    },
  }, { setting: "value" }],
];

interface ThemeConfig {
  /** Theme entry point path or module name */
  path?: string;
  
  /** Theme extends another theme */
  extend?: string;
  
  /** Theme-specific configuration */
  [key: string]: any;
}

// Using theme by name
const themeConfig1 = "@vuepress/theme-default";

// Using theme with configuration
const themeConfig2 = {
  path: "@vuepress/theme-default",
  nav: [
    { text: "Home", link: "/" },
    { text: "Guide", link: "/guide/" },
  ],
  sidebar: "auto",
  search: false,
};

// Custom theme path
const themeConfig3 = {
  path: "./my-custom-theme",
  customOption: "value",
};

interface DevOptions {
  /** Source directory */
  sourceDir?: string;
  
  /** Plugin configurations */
  plugins?: PluginConfig[];
  
  /** Theme configuration */
  theme?: string | ThemeConfig;
  
  /** Temporary directory */
  temp?: string;
  
  /** Site configuration */
  siteConfig?: SiteConfig;
  
  /** Development server host */
  host?: string;
  
  /** Development server port */
  port?: number;
  
  /** Open browser automatically */
  open?: boolean;
}

interface BuildOptions {
  /** Source directory */
  sourceDir?: string;
  
  /** Plugin configurations */
  plugins?: PluginConfig[];
  
  /** Theme configuration */
  theme?: string | ThemeConfig;
  
  /** Output directory */
  dest?: string;
  
  /** Temporary directory */
  temp?: string;
  
  /** Site configuration */
  siteConfig?: SiteConfig;
  
  /** Silent build output */
  silent?: boolean;
  
  /** Debug mode */
  debug?: boolean;
}

interface PageData {
  /** Page title */
  title: string;
  
  /** URL path */
  path: string;
  
  /** Unique page identifier */
  key: string;
  
  /** Page frontmatter */
  frontmatter: any;
  
  /** Extracted headers */
  headers?: Header[];
  
  /** Page excerpt HTML */
  excerpt?: string;
  
  /** Relative file path */
  relativePath?: string;
  
  /** Regular path without permalink */
  regularPath: string;
}

interface SiteData {
  /** Site title */
  title: string;
  
  /** Site description */
  description: string;
  
  /** Base URL path */
  base: string;
  
  /** HTML head tags */
  headTags: HeadTag[];
  
  /** All page data */
  pages: PageData[];
  
  /** Theme configuration */
  themeConfig: any;
  
  /** Locale configuration */
  locales?: LocaleConfig;
}

interface Header {
  /** Header text content */
  title: string;
  
  /** URL anchor slug */
  slug: string;
  
  /** Header level (1-6) */
  level: number;
  
  /** Nested child headers */
  children?: Header[];
}

// Typical header structure from markdown:
// # Main Title
// ## Section 1  
// ### Subsection 1.1
// ### Subsection 1.2
// ## Section 2

const headers = [
  {
    title: "Main Title",
    slug: "main-title", 
    level: 1,
    children: [
      {
        title: "Section 1",
        slug: "section-1",
        level: 2,
        children: [
          { title: "Subsection 1.1", slug: "subsection-1-1", level: 3 },
          { title: "Subsection 1.2", slug: "subsection-1-2", level: 3 },
        ],
      },
      {
        title: "Section 2",
        slug: "section-2",
        level: 2,
      },
    ],
  },
];