0
# Configuration API
1

2
VitePress configuration system provides type-safe configuration helpers and comprehensive configuration interfaces for building static sites with custom themes, markdown processing, and internationalization support.
3

4
## Capabilities
5

6
### Core Configuration Functions
7

8
Configuration helper functions for type safety and configuration resolution.
9

10
#### defineConfig
11

12
Type helper for defining VitePress configuration with default theme support.
13

14
```typescript { .api }
15
/**
16
 * Creates a typed VitePress configuration object with default theme support
17
 * @param config - VitePress configuration with DefaultTheme.Config
18
 * @returns The same config object (identity function for type inference)
19
 */
20
function defineConfig(config: UserConfig<DefaultTheme.Config>): UserConfig<DefaultTheme.Config>;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { defineConfig } from "vitepress";
27

28
export default defineConfig({
29
  title: "My Site",
30
  description: "A documentation site built with VitePress",
31
  themeConfig: {
32
    nav: [
33
      { text: "Home", link: "/" },
34
      { text: "Guide", link: "/guide/" }
35
    ],
36
    sidebar: {
37
      "/guide/": [
38
        {
39
          text: "Getting Started",
40
          items: [
41
            { text: "Introduction", link: "/guide/introduction" },
42
            { text: "Setup", link: "/guide/setup" }
43
          ]
44
        }
45
      ]
46
    }
47
  }
48
});
49
```
50

51
#### defineConfigWithTheme
52

53
Type helper for defining VitePress configuration with custom theme support.
54

55
```typescript { .api }
56
/**
57
 * Creates a typed VitePress configuration object with custom theme support
58
 * @param config - VitePress configuration with generic ThemeConfig type
59
 * @returns The same config object (identity function for type inference)
60
 */
61
function defineConfigWithTheme<ThemeConfig>(
62
  config: UserConfig<ThemeConfig>
63
): UserConfig<ThemeConfig>;
64
```
65

66
**Usage Example:**
67

68
```typescript
69
import { defineConfigWithTheme } from "vitepress";
70

71
interface CustomTheme {
72
  primaryColor: string;
73
  customNavbar: boolean;
74
}
75

76
export default defineConfigWithTheme<CustomTheme>({
77
  title: "Custom Theme Site",
78
  themeConfig: {
79
    primaryColor: "#3eaf7c",
80
    customNavbar: true
81
  }
82
});
83
```
84

85
#### resolveConfig
86

87
Resolves and normalizes VitePress configuration for internal use.
88

89
```typescript { .api }
90
/**
91
 * Resolves and normalizes VitePress configuration
92
 * @param root - Project root directory (defaults to process.cwd())
93
 * @param command - Build command type (defaults to 'serve')
94
 * @param mode - Development mode string (defaults to 'development')
95
 * @returns Promise resolving to fully resolved SiteConfig
96
 */
97
function resolveConfig(
98
  root?: string,
99
  command?: "serve" | "build",
100
  mode?: string
101
): Promise<SiteConfig>;
102
```
103

104
**Usage Example:**
105

106
```typescript
107
import { resolveConfig } from "vitepress";
108

109
// Resolve configuration for build
110
const config = await resolveConfig("./docs", "build", "production");
111
console.log("Resolved site config:", config.site);
112
console.log("Output directory:", config.outDir);
113
```
114

115
#### resolveUserConfig
116

117
Loads and resolves user configuration from config file.
118

119
```typescript { .api }
120
/**
121
 * Loads and resolves user configuration from config file
122
 * @param root - Project root directory
123
 * @param command - Build command type
124
 * @param mode - Development mode string
125
 * @returns Tuple of [userConfig, configPath, configDependencies]
126
 */
127
function resolveUserConfig(
128
  root: string,
129
  command: "serve" | "build",
130
  mode: string
131
): Promise<[UserConfig, string?, string[]]>;
132
```
133

134
#### resolveSiteData
135

136
Resolves site data from user configuration.
137

138
```typescript { .api }
139
/**
140
 * Resolves site data from user configuration
141
 * @param root - Project root directory
142
 * @param userConfig - User configuration object
143
 * @param command - Build command type
144
 * @param mode - Development mode string
145
 * @returns Promise resolving to SiteData object
146
 */
147
function resolveSiteData(
148
  root: string,
149
  userConfig?: UserConfig,
150
  command?: "serve" | "build",
151
  mode?: string
152
): Promise<SiteData>;
153
```
154

155
#### mergeConfig
156

157
Merges two VitePress configuration objects with proper deep merging.
158

159
```typescript { .api }
160
/**
161
 * Merges two VitePress configuration objects
162
 * @param a - First configuration object
163
 * @param b - Second configuration object (takes priority)
164
 * @param isRoot - Whether this is a root level merge
165
 * @returns Merged UserConfig object
166
 */
167
function mergeConfig(
168
  a: UserConfig,
169
  b: UserConfig,
170
  isRoot?: boolean
171
): UserConfig;
172
```
173

174
**Usage Example:**
175

176
```typescript
177
import { mergeConfig, defineConfig } from "vitepress";
178

179
const baseConfig = defineConfig({
180
  title: "Base Site",
181
  themeConfig: {
182
    nav: [{ text: "Home", link: "/" }]
183
  }
184
});
185

186
const extendedConfig = defineConfig({
187
  description: "Extended site description",
188
  themeConfig: {
189
    nav: [
190
      { text: "Home", link: "/" },
191
      { text: "About", link: "/about" }
192
    ]
193
  }
194
});
195

196
const merged = mergeConfig(baseConfig, extendedConfig);
197
```
198

199
### Configuration Types
200

201
Core interfaces for VitePress configuration.
202

203
#### UserConfig
204

205
Main configuration interface for VitePress sites.
206

207
```typescript { .api }
208
interface UserConfig<ThemeConfig = any> {
209
  /**
210
   * Configuration to extend from
211
   */
212
  extends?: UserConfig<ThemeConfig>;
213
  
214
  /**
215
   * Base URL path for the site
216
   * @default '/'
217
   */
218
  base?: string;
219
  
220
  /**
221
   * Source directory containing markdown files
222
   * @default '.'
223
   */
224
  srcDir?: string;
225
  
226
  /**
227
   * Output directory for built site
228
   * @default '.vitepress/dist'
229
   */
230
  outDir?: string;
231
  
232
  /**
233
   * Cache directory for temporary files
234
   * @default '.vitepress/cache'
235
   */
236
  cacheDir?: string;
237
  
238
  /**
239
   * Site title
240
   */
241
  title?: string;
242
  
243
  /**
244
   * Site title template or boolean to disable
245
   */
246
  titleTemplate?: string | boolean;
247
  
248
  /**
249
   * Site description
250
   */
251
  description?: string;
252
  
253
  /**
254
   * HTML head tags configuration
255
   */
256
  head?: HeadConfig[];
257
  
258
  /**
259
   * Default language for the site
260
   * @default 'en-US'
261
   */
262
  lang?: string;
263
  
264
  /**
265
   * Text direction for the site
266
   * @default 'ltr'
267
   */
268
  dir?: string;
269
  
270
  /**
271
   * Theme-specific configuration
272
   */
273
  themeConfig?: ThemeConfig;
274
  
275
  /**
276
   * Markdown processing options
277
   */
278
  markdown?: MarkdownOptions;
279
  
280
  /**
281
   * Vite configuration
282
   */
283
  vite?: ViteUserConfig;
284
  
285
  /**
286
   * Vue configuration
287
   */
288
  vue?: VueOptions;
289
  
290
  /**
291
   * Multi-language configuration
292
   */
293
  locales?: LocaleConfig<ThemeConfig>;
294
  
295
  /**
296
   * Dark mode appearance configuration
297
   * @default true
298
   */
299
  appearance?: 
300
    | boolean 
301
    | 'dark' 
302
    | 'force-dark' 
303
    | 'force-auto'
304
    | (Omit<UseDarkOptions, 'initialValue'> & { 
305
        initialValue?: 'dark' 
306
      });
307
  
308
  /**
309
   * Last updated timestamp feature
310
   * @default false
311
   */
312
  lastUpdated?: boolean;
313
  
314
  /**
315
   * Clean URLs without .html extension
316
   * @default false
317
   */
318
  cleanUrls?: boolean;
319
  
320
  /**
321
   * Enable Multi-Page Application mode
322
   * @default false
323
   */
324
  mpa?: boolean;
325
  
326
  /**
327
   * URL rewrites configuration
328
   */
329
  rewrites?: Record<string, string>;
330
  
331
  /**
332
   * Sitemap generation options
333
   */
334
  sitemap?: {
335
    hostname: string;
336
    transformItems?: (items: SitemapItem[]) => Awaitable<SitemapItem[]>;
337
  };
338
  
339
  /**
340
   * Meta chunk options for performance
341
   * @default false
342
   */
343
  metaChunk?: boolean;
344
  
345
  /**
346
   * Build concurrency control
347
   */
348
  buildConcurrency?: number;
349
  
350
  /**
351
   * Scroll offset for anchor links
352
   */
353
  scrollOffset?: 
354
    | number 
355
    | string 
356
    | string[] 
357
    | { selector: string | string[]; padding: number };
358
  
359
  /**
360
   * Ignore dead links patterns
361
   */
362
  ignoreDeadLinks?: 
363
    | boolean 
364
    | 'localhostLinks' 
365
    | (string | RegExp | ((link: string) => boolean))[];
366
  
367
  /**
368
   * Transform functions for build pipeline
369
   */
370
  transformHead?: (ctx: TransformContext) => Awaitable<HeadConfig[]>;
371
  transformHtml?: (code: string, id: string, ctx: TransformContext) => Awaitable<string>;
372
  transformPageData?: (pageData: PageData, ctx: TransformContext) => Awaitable<Partial<PageData> | { [key: string]: any } | void>;
373
  
374
  /**
375
   * Build hooks
376
   */
377
  buildEnd?: (siteConfig: SiteConfig) => Awaitable<void>;
378
  postRender?: (context: SSGContext) => Awaitable<SSGContext | void>;
379
}
380
```
381

382
#### SiteConfig
383

384
Resolved configuration used internally by VitePress.
385

386
```typescript { .api }
387
interface SiteConfig<ThemeConfig = any> extends UserConfig<ThemeConfig> {
388
  /**
389
   * Resolved project root directory
390
   */
391
  root: string;
392
  
393
  /**
394
   * Resolved source directory path
395
   */
396
  srcDir: string;
397
  
398
  /**
399
   * Resolved site data
400
   */
401
  site: SiteData<ThemeConfig>;
402
  
403
  /**
404
   * Configuration file path
405
   */
406
  configPath?: string;
407
  
408
  /**
409
   * Configuration dependencies
410
   */
411
  configDeps: string[];
412
  
413
  /**
414
   * Discovered pages
415
   */
416
  pages: string[];
417
  
418
  /**
419
   * Dynamic route patterns
420
   */
421
  dynamicRoutes: SiteConfig['pages'];
422
  
423
  /**
424
   * Rewrites mapping
425
   */
426
  rewrites: SiteConfig['rewrites'];
427
  
428
  /**
429
   * Logger instance
430
   */
431
  logger: Logger;
432
  
433
  /**
434
   * Temporary directory path
435
   */
436
  tempDir: string;
437
  
438
  /**
439
   * Markdown renderer instance
440
   */
441
  markdown: MarkdownRenderer;
442
}
443
```
444

445
#### MarkdownOptions
446

447
Configuration options for markdown processing.
448

449
```typescript { .api }
450
interface MarkdownOptions {
451
  /**
452
   * Show line numbers in code blocks
453
   * @default false
454
   */
455
  lineNumbers?: boolean;
456
  
457
  /**
458
   * Custom MarkdownIt configuration
459
   */
460
  config?: (md: MarkdownIt) => void;
461
  
462
  /**
463
   * Syntax highlighting theme
464
   */
465
  theme?: 
466
    | ThemeOptions
467
    | { light: ThemeOptions; dark: ThemeOptions };
468
  
469
  /**
470
   * Supported programming languages
471
   */
472
  languages?: LanguageInput[];
473
  
474
  /**
475
   * Custom anchor options
476
   */
477
  anchor?: AnchorOptions;
478
  
479
  /**
480
   * Table of contents options
481
   */
482
  toc?: TocOptions;
483
  
484
  /**
485
   * External links attributes
486
   */
487
  externalLinks?: Record<string, string>;
488
  
489
  /**
490
   * Enable markdown caching
491
   * @default true
492
   */
493
  cache?: boolean;
494
  
495
  /**
496
   * Math rendering options
497
   */
498
  math?: boolean;
499
  
500
  /**
501
   * Image processing options
502
   */
503
  image?: {
504
    lazy?: boolean;
505
    lazyLoading?: boolean;
506
  };
507
  
508
  /**
509
   * Container options
510
   */
511
  container?: {
512
    tipLabel?: string;
513
    warningLabel?: string;
514
    dangerLabel?: string;
515
    infoLabel?: string;
516
    detailsLabel?: string;
517
  };
518
}
519
```
520

521
#### LocaleSpecificConfig
522

523
Configuration for specific locale.
524

525
```typescript { .api }
526
interface LocaleSpecificConfig<ThemeConfig = any> {
527
  /**
528
   * Language code for this locale
529
   */
530
  lang?: string;
531
  
532
  /**
533
   * Text direction
534
   */
535
  dir?: string;
536
  
537
  /**
538
   * Site title for this locale
539
   */
540
  title?: string;
541
  
542
  /**
543
   * Title template for this locale
544
   */
545
  titleTemplate?: string | boolean;
546
  
547
  /**
548
   * Site description for this locale
549
   */
550
  description?: string;
551
  
552
  /**
553
   * HTML head configuration for this locale
554
   */
555
  head?: HeadConfig[];
556
  
557
  /**
558
   * Theme configuration for this locale
559
   */
560
  themeConfig?: ThemeConfig;
561
}
562
```
563

564
### Transform Context Types
565

566
Context objects passed to transform functions.
567

568
```typescript { .api }
569
interface TransformContext {
570
  /**
571
   * Site configuration
572
   */
573
  siteConfig: SiteConfig;
574
  
575
  /**
576
   * Site data
577
   */
578
  siteData: SiteData;
579
  
580
  /**
581
   * Current page data
582
   */
583
  pageData: PageData;
584
  
585
  /**
586
   * Page title
587
   */
588
  title: string;
589
  
590
  /**
591
   * Page description
592
   */
593
  description: string;
594
  
595
  /**
596
   * HTML head configuration
597
   */
598
  head: HeadConfig[];
599
  
600
  /**
601
   * Current locale index
602
   */
603
  localeIndex: string;
604
  
605
  /**
606
   * Content of the page
607
   */
608
  content: string;
609
}
610

611
interface SSGContext extends SSRContext {
612
  /**
613
   * Rendered content
614
   */
615
  content: string;
616
  
617
  /**
618
   * Social icons used in the page
619
   */
620
  vpSocialIcons: Set<string>;
621
}
622
```