Configuration Types

import type { 
  DocusaurusConfig, 
  MarkdownConfig, 
  FutureConfig, 
  Config,
  ReportingSeverity,
  RouterType,
  ThemeConfig,
  SiteStorage
} from "@docusaurus/types";
import type { ProcessorOptions } from "@mdx-js/mdx";
import type { RuleSetRule } from "webpack";
import type { DeepPartial, Overwrite } from "utility-types";

/**
 * Complete Docusaurus configuration, after validation/normalization
 */
interface DocusaurusConfig {
  /** Title for your website. Will be used in metadata and as browser tab title. */
  title: string;
  /** URL for your website. This can also be considered the top-level hostname. */
  url: string;
  /** Base URL path. Always has both leading and trailing slash. */
  baseUrl: string;
  /** Path to your site favicon; must be a URL that can be used in link's href. */
  favicon?: string;
  /** Control trailing slash behavior for URLs/links */
  trailingSlash: boolean | undefined;
  /** The i18n configuration object to localize your site */
  i18n: I18nConfig;
  /** Docusaurus future flags and experimental features */
  future: FutureConfig;
  /** Adds noindex meta tag to prevent search engine indexing */
  noIndex: boolean;
  /** Behavior when broken links are detected */
  onBrokenLinks: ReportingSeverity;
  /** Behavior when broken anchors are detected */
  onBrokenAnchors: ReportingSeverity;
  /** Behavior when broken markdown links are detected */
  onBrokenMarkdownLinks: ReportingSeverity;
  /** Behavior when duplicate routes are detected */
  onDuplicateRoutes: ReportingSeverity;
  /** The tagline for your website */
  tagline: string;
  /** GitHub user or organization that owns the repository */
  organizationName?: string;
  /** GitHub repository name */
  projectName?: string;
  /** Git branch to deploy static files to */
  deploymentBranch?: string;
  /** GitHub Enterprise hostname */
  githubHost?: string;
  /** GitHub Enterprise port */
  githubPort?: string;
  /** Theme configuration object */
  themeConfig: ThemeConfig;
  /** List of plugins */
  plugins: PluginConfig[];
  /** List of themes */
  themes: PluginConfig[];
  /** List of presets */
  presets: PresetConfig[];
  /** Custom fields for additional site data */
  customFields?: {[key: string]: unknown};
  /** Static directories to copy to build output */
  staticDirectories: string[];
  /** HTML tags to insert in the head */
  headTags: HtmlTagObject[];
  /** Scripts to load globally */
  scripts: (string | {src: string; [key: string]: string | boolean | undefined})[];
  /** Stylesheets to load globally */
  stylesheets: (string | {href: string; [key: string]: string | boolean | undefined})[];
  /** Client modules to load globally */
  clientModules: string[];
  /** Custom HTML template for SSR */
  ssrTemplate?: string;
  /** Title delimiter in generated page titles */
  titleDelimiter: string;
  /** Show banner when CSS/JS fails to load */
  baseUrlIssueBanner: boolean;
  /** Webpack-related options */
  webpack?: {
    jsLoader?: 'babel' | ((isServer: boolean) => RuleSetRule);
  };
  /** Markdown processing configuration */
  markdown: MarkdownConfig;
}

/**
 * User-provided Docusaurus config for type-safety and IDE auto-complete
 */
type Config = Overwrite<
  DeepPartial<DocusaurusConfig>,
  {
    title: DocusaurusConfig['title'];
    url: DocusaurusConfig['url'];
    baseUrl: DocusaurusConfig['baseUrl'];
    future?: Overwrite<
      DeepPartial<FutureConfig>,
      {
        v4?: boolean | Partial<FutureV4Config>;
        experimental_faster?: boolean | Partial<FasterConfig>;
      }
    >;
  }
>;

/**
 * Markdown processing configuration
 */
interface MarkdownConfig {
  /** Markdown format: 'mdx' for JSX support, 'md' for CommonMark, 'detect' for auto-detection */
  format: 'mdx' | 'md' | 'detect';
  /** Custom front matter parser function */
  parseFrontMatter: ParseFrontMatter;
  /** Enable mermaid diagram rendering */
  mermaid: boolean;
  /** MDX content preprocessor function */
  preprocessor?: MarkdownPreprocessor;
  /** MDX v1 compatibility options */
  mdx1Compat: MDX1CompatOptions;
  /** Remark-rehype processing options */
  remarkRehypeOptions: RemarkRehypeOptions;
  /** Anchor generation configuration */
  anchors: MarkdownAnchorsConfig;
}

/**
 * Function to preprocess MDX content before compilation
 */
type MarkdownPreprocessor = (args: {
  filePath: string;
  fileContent: string;
}) => string;

/**
 * MDX v1 compatibility flags
 */
interface MDX1CompatOptions {
  comments: boolean;
  admonitions: boolean;
  headingIds: boolean;
}

/**
 * Configuration for markdown anchor generation
 */
interface MarkdownAnchorsConfig {
  /** Preserve case when generating anchor IDs */
  maintainCase: boolean;
}

/**
 * Parameters for front matter parsing
 */
interface ParseFrontMatterParams {
  filePath: string;
  fileContent: string;
}

/**
 * Result of front matter parsing
 */
interface ParseFrontMatterResult {
  frontMatter: {[key: string]: unknown};
  content: string;
}

/**
 * Default front matter parser function
 */
type DefaultParseFrontMatter = (
  params: ParseFrontMatterParams,
) => Promise<ParseFrontMatterResult>;

/**
 * Custom front matter parser function
 */
type ParseFrontMatter = (
  params: ParseFrontMatterParams & {
    defaultParseFrontMatter: DefaultParseFrontMatter;
  },
) => Promise<ParseFrontMatterResult>;

/**
 * Future flags and experimental features
 */
interface FutureConfig {
  /** Version 4 future flags */
  v4: FutureV4Config;
  /** Experimental performance optimizations */
  experimental_faster: FasterConfig;
  /** Experimental storage configuration */
  experimental_storage: StorageConfig;
  /** Experimental router type (browser or hash) */
  experimental_router: RouterType;
}

/**
 * Version 4 breaking change flags
 */
interface FutureV4Config {
  removeLegacyPostBuildHeadAttribute: boolean;
  useCssCascadeLayers: boolean;
}

/**
 * Performance optimization flags
 */
interface FasterConfig {
  swcJsLoader: boolean;
  swcJsMinimizer: boolean;
  swcHtmlMinimizer: boolean;
  lightningCssMinimizer: boolean;
  mdxCrossCompilerCache: boolean;
  rspackBundler: boolean;
  rspackPersistentCache: boolean;
  ssgWorkerThreads: boolean;
}

/**
 * Browser storage configuration
 */
interface StorageConfig {
  type: SiteStorage['type'];
  namespace: boolean | string;
}

/**
 * Flexible theme configuration object
 */
interface ThemeConfig {
  [key: string]: unknown;
}

/**
 * Reporting severity levels for various validation checks
 */
type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';

/**
 * Router types supported by Docusaurus
 */
type RouterType = 'browser' | 'hash';

/**
 * Remark-rehype processing options from MDX
 */
type RemarkRehypeOptions = ProcessorOptions['remarkRehypeOptions'];