0
# Types and Configuration
1

2
Common types, interfaces, and configuration options used throughout the VuePress API.
3

4
## Core Types
5

6
### SiteConfig
7

8
Site-wide configuration options that control the behavior and appearance of the VuePress site.
9

10
```javascript { .api }
11
interface SiteConfig {
12
  /** Site title displayed in the header */
13
  title?: string;
14
  
15
  /** Site description for SEO and meta tags */
16
  description?: string;
17
  
18
  /** Base URL path for deployment (default: "/") */
19
  base?: string;
20
  
21
  /** HTML head tags to inject */
22
  head?: HeadTag[];
23
  
24
  /** Theme-specific configuration */
25
  themeConfig?: any;
26
  
27
  /** Markdown processor configuration */
28
  markdown?: MarkdownConfig;
29
  
30
  /** File patterns to include when scanning for pages */
31
  patterns?: string[];
32
  
33
  /** Default permalink pattern for pages */
34
  permalink?: string;
35
  
36
  /** Locale configuration for internationalization */
37
  locales?: LocaleConfig;
38
  
39
  /** Temporary directory override */
40
  temp?: string;
41
  
42
  /** Build output directory override */
43
  dest?: string;
44
  
45
  /** Plugin configurations */
46
  plugins?: PluginConfig[];
47
  
48
  /** Theme configuration */
49
  theme?: string | ThemeConfig;
50
}
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const siteConfig = {
57
  title: "My Documentation",
58
  description: "Comprehensive guide and API reference",
59
  base: "/docs/",
60
  head: [
61
    ["link", { rel: "icon", href: "/favicon.ico" }],
62
    ["meta", { name: "theme-color", content: "#3eaf7c" }],
63
  ],
64
  themeConfig: {
65
    nav: [
66
      { text: "Home", link: "/" },
67
      { text: "Guide", link: "/guide/" },
68
      { text: "API", link: "/api/" },
69
    ],
70
    sidebar: {
71
      "/guide/": ["", "installation", "configuration"],
72
      "/api/": ["", "core", "plugins"],
73
    },
74
  },
75
  markdown: {
76
    lineNumbers: true,
77
    extractHeaders: ["h1", "h2", "h3"],
78
  },
79
  plugins: [
80
    ["@vuepress/plugin-search"],
81
    ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
82
  ],
83
};
84
```
85

86
### MarkdownConfig
87

88
Configuration options for the markdown processor.
89

90
```javascript { .api }
91
interface MarkdownConfig {
92
  /** Show line numbers in code blocks */
93
  lineNumbers?: boolean;
94
  
95
  /** Header levels to extract for navigation */
96
  extractHeaders?: string[];
97
  
98
  /** Markdown-it options */
99
  options?: any;
100
  
101
  /** Custom markdown-it plugins */
102
  plugins?: any[];
103
  
104
  /** Anchor options for headers */
105
  anchor?: AnchorOptions;
106
  
107
  /** Table of contents options */
108
  toc?: TocOptions;
109
  
110
  /** External link options */
111
  externalLinks?: ExternalLinkOptions;
112
}
113

114
interface AnchorOptions {
115
  /** Permalink symbol */
116
  permalink?: boolean;
117
  /** Permalink symbol position */
118
  permalinkBefore?: boolean;
119
  /** Permalink symbol */
120
  permalinkSymbol?: string;
121
}
122
```
123

124
**Usage Examples:**
125

126
```javascript
127
const markdownConfig = {
128
  lineNumbers: true,
129
  extractHeaders: ["h1", "h2", "h3", "h4"],
130
  anchor: {
131
    permalink: true,
132
    permalinkBefore: true,
133
    permalinkSymbol: "#",
134
  },
135
  plugins: [
136
    "markdown-it-footnote",
137
    ["markdown-it-container", "warning"],
138
  ],
139
};
140
```
141

142
### HeadTag
143

144
HTML head tag configuration for injecting custom elements.
145

146
```javascript { .api }
147
type HeadTag = [string, { [key: string]: string }, string?];
148

149
// Format: [tagName, attributes, innerHTML?]
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
const headTags = [
156
  // Basic meta tag
157
  ["meta", { name: "author", content: "John Doe" }],
158
  
159
  // Link tag
160
  ["link", { rel: "stylesheet", href: "/custom.css" }],
161
  
162
  // Script tag with content
163
  ["script", {}, "console.log('Custom script');"],
164
  
165
  // Script tag with src
166
  ["script", { src: "/analytics.js", async: "true" }],
167
  
168
  // Favicon
169
  ["link", { rel: "icon", href: "/favicon.png", type: "image/png" }],
170
];
171
```
172

173
### LocaleConfig
174

175
Configuration for internationalization and multiple locales.
176

177
```javascript { .api }
178
interface LocaleConfig {
179
  [path: string]: LocaleOptions;
180
}
181

182
interface LocaleOptions {
183
  /** Locale language code */
184
  lang?: string;
185
  
186
  /** Locale title override */
187
  title?: string;
188
  
189
  /** Locale description override */
190
  description?: string;
191
  
192
  /** Locale-specific theme config */
193
  themeConfig?: any;
194
}
195
```
196

197
**Usage Examples:**
198

199
```javascript
200
const locales = {
201
  "/": {
202
    lang: "en-US",
203
    title: "Documentation",
204
    description: "English documentation",
205
  },
206
  "/zh/": {
207
    lang: "zh-CN",
208
    title: "文档",
209
    description: "中文文档",
210
    themeConfig: {
211
      nav: [
212
        { text: "首页", link: "/zh/" },
213
        { text: "指南", link: "/zh/guide/" },
214
      ],
215
    },
216
  },
217
  "/es/": {
218
    lang: "es-ES", 
219
    title: "Documentación",
220
    description: "Documentación en español",
221
  },
222
};
223
```
224

225
## Plugin Types
226

227
### PluginConfig
228

229
Various ways to configure plugins in VuePress.
230

231
```javascript { .api }
232
type PluginConfig = 
233
  | string                    // Plugin name
234
  | [string, any]            // Plugin name with options
235
  | Plugin                   // Plugin object
236
  | [Plugin, any];           // Plugin object with options
237

238
interface Plugin {
239
  /** Plugin identifier */
240
  name?: string;
241
  
242
  /** Allow multiple instances of this plugin */
243
  multiple?: boolean;
244
  
245
  /** Child plugins to register */
246
  plugins?: PluginConfig[];
247
  
248
  /** Plugin implementation */
249
  [optionName: string]: any;
250
}
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
// Different plugin configuration formats
257
const pluginConfigs = [
258
  // String name (uses defaults)
259
  "@vuepress/plugin-blog",
260
  
261
  // String name with options
262
  ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
263
  
264
  // Plugin object
265
  {
266
    name: "custom-plugin",
267
    ready() {
268
      console.log("Ready!");
269
    },
270
  },
271
  
272
  // Plugin object with options
273
  [{
274
    name: "configurable-plugin",
275
    ready(config) {
276
      console.log(`Config: ${JSON.stringify(config)}`);
277
    },
278
  }, { setting: "value" }],
279
];
280
```
281

282
### ThemeConfig
283

284
Theme configuration and customization options.
285

286
```javascript { .api }
287
interface ThemeConfig {
288
  /** Theme entry point path or module name */
289
  path?: string;
290
  
291
  /** Theme extends another theme */
292
  extend?: string;
293
  
294
  /** Theme-specific configuration */
295
  [key: string]: any;
296
}
297
```
298

299
**Usage Examples:**
300

301
```javascript
302
// Using theme by name
303
const themeConfig1 = "@vuepress/theme-default";
304

305
// Using theme with configuration
306
const themeConfig2 = {
307
  path: "@vuepress/theme-default",
308
  nav: [
309
    { text: "Home", link: "/" },
310
    { text: "Guide", link: "/guide/" },
311
  ],
312
  sidebar: "auto",
313
  search: false,
314
};
315

316
// Custom theme path
317
const themeConfig3 = {
318
  path: "./my-custom-theme",
319
  customOption: "value",
320
};
321
```
322

323
## Development Types
324

325
### DevOptions
326

327
Configuration options for development server.
328

329
```javascript { .api }
330
interface DevOptions {
331
  /** Source directory */
332
  sourceDir?: string;
333
  
334
  /** Plugin configurations */
335
  plugins?: PluginConfig[];
336
  
337
  /** Theme configuration */
338
  theme?: string | ThemeConfig;
339
  
340
  /** Temporary directory */
341
  temp?: string;
342
  
343
  /** Site configuration */
344
  siteConfig?: SiteConfig;
345
  
346
  /** Development server host */
347
  host?: string;
348
  
349
  /** Development server port */
350
  port?: number;
351
  
352
  /** Open browser automatically */
353
  open?: boolean;
354
}
355
```
356

357
### BuildOptions
358

359
Configuration options for production builds.
360

361
```javascript { .api }
362
interface BuildOptions {
363
  /** Source directory */
364
  sourceDir?: string;
365
  
366
  /** Plugin configurations */
367
  plugins?: PluginConfig[];
368
  
369
  /** Theme configuration */
370
  theme?: string | ThemeConfig;
371
  
372
  /** Output directory */
373
  dest?: string;
374
  
375
  /** Temporary directory */
376
  temp?: string;
377
  
378
  /** Site configuration */
379
  siteConfig?: SiteConfig;
380
  
381
  /** Silent build output */
382
  silent?: boolean;
383
  
384
  /** Debug mode */
385
  debug?: boolean;
386
}
387
```
388

389
## Utility Types
390

391
### PageData
392

393
Serialized page data for client-side consumption.
394

395
```javascript { .api }
396
interface PageData {
397
  /** Page title */
398
  title: string;
399
  
400
  /** URL path */
401
  path: string;
402
  
403
  /** Unique page identifier */
404
  key: string;
405
  
406
  /** Page frontmatter */
407
  frontmatter: any;
408
  
409
  /** Extracted headers */
410
  headers?: Header[];
411
  
412
  /** Page excerpt HTML */
413
  excerpt?: string;
414
  
415
  /** Relative file path */
416
  relativePath?: string;
417
  
418
  /** Regular path without permalink */
419
  regularPath: string;
420
}
421
```
422

423
### SiteData
424

425
Complete site data delivered to client.
426

427
```javascript { .api }
428
interface SiteData {
429
  /** Site title */
430
  title: string;
431
  
432
  /** Site description */
433
  description: string;
434
  
435
  /** Base URL path */
436
  base: string;
437
  
438
  /** HTML head tags */
439
  headTags: HeadTag[];
440
  
441
  /** All page data */
442
  pages: PageData[];
443
  
444
  /** Theme configuration */
445
  themeConfig: any;
446
  
447
  /** Locale configuration */
448
  locales?: LocaleConfig;
449
}
450
```
451

452
### Header
453

454
Page header information extracted from markdown.
455

456
```javascript { .api }
457
interface Header {
458
  /** Header text content */
459
  title: string;
460
  
461
  /** URL anchor slug */
462
  slug: string;
463
  
464
  /** Header level (1-6) */
465
  level: number;
466
  
467
  /** Nested child headers */
468
  children?: Header[];
469
}
470
```
471

472
**Usage Examples:**
473

474
```javascript
475
// Typical header structure from markdown:
476
// # Main Title
477
// ## Section 1  
478
// ### Subsection 1.1
479
// ### Subsection 1.2
480
// ## Section 2
481

482
const headers = [
483
  {
484
    title: "Main Title",
485
    slug: "main-title", 
486
    level: 1,
487
    children: [
488
      {
489
        title: "Section 1",
490
        slug: "section-1",
491
        level: 2,
492
        children: [
493
          { title: "Subsection 1.1", slug: "subsection-1-1", level: 3 },
494
          { title: "Subsection 1.2", slug: "subsection-1-2", level: 3 },
495
        ],
496
      },
497
      {
498
        title: "Section 2",
499
        slug: "section-2",
500
        level: 2,
501
      },
502
    ],
503
  },
504
];
505
```