0
# Plugin System
1

2
Comprehensive plugin architecture providing hooks for customizing every aspect of the VuePress build process, from markdown processing to webpack configuration.
3

4
## Capabilities
5

6
### PluginAPI Class
7

8
Core plugin management system that handles plugin registration, initialization, and option processing.
9

10
```javascript { .api }
11
/**
12
 * Plugin management and execution system
13
 */
14
class PluginAPI {
15
  /**
16
   * Create a new PluginAPI instance
17
   * @param context - App instance context
18
   */
19
  constructor(context: App);
20
  
21
  /** Plugin collections */
22
  readonly enabledPlugins: Plugin[];
23
  readonly disabledPlugins: Plugin[];
24
  readonly options: { [optionName: string]: Option };
25
}
26
```
27

28
### use Method
29

30
Registers a plugin with the plugin system.
31

32
```javascript { .api }
33
/**
34
 * Register a plugin with optional configuration
35
 * @param pluginRaw - Plugin name, path, or object
36
 * @param pluginOptions - Plugin configuration options
37
 * @returns PluginAPI instance for chaining
38
 */
39
use(pluginRaw: string | Plugin | any, pluginOptions?: any): PluginAPI;
40
```
41

42
**Usage Examples:**
43

44
```javascript
45
const { createApp } = require("vuepress");
46

47
const app = createApp({ sourceDir: "./docs" });
48

49
// Register plugins using string names
50
app.pluginAPI
51
  .use("@vuepress/plugin-blog")
52
  .use("@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" })
53
  .use("@vuepress/plugin-pwa", {
54
    serviceWorker: true,
55
    updatePopup: true,
56
  });
57

58
// Register plugin using object
59
app.pluginAPI.use({
60
  name: "custom-plugin",
61
  ready() {
62
    console.log("Custom plugin is ready!");
63
  },
64
  generated() {
65
    console.log("Site generation complete!");
66
  },
67
});
68

69
// Chain multiple plugin registrations
70
app.pluginAPI
71
  .use("plugin-one")
72
  .use("plugin-two", { option: "value" })
73
  .use("plugin-three");
74
```
75

76
### useByPluginsConfig Method
77

78
Registers multiple plugins using configuration array format.
79

80
```javascript { .api }
81
/**
82
 * Register plugins using configuration array
83
 * @param pluginsConfig - Array of plugin configurations
84
 * @returns PluginAPI instance for chaining
85
 */
86
useByPluginsConfig(pluginsConfig: PluginConfig[]): PluginAPI;
87

88
type PluginConfig = 
89
  | string 
90
  | [string, any] 
91
  | Plugin 
92
  | [Plugin, any];
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
const pluginsConfig = [
99
  "@vuepress/plugin-blog",
100
  ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
101
  ["@vuepress/plugin-pwa", { 
102
    serviceWorker: true,
103
    updatePopup: {
104
      message: "New content is available.",
105
      buttonText: "Refresh"
106
    }
107
  }],
108
];
109

110
app.pluginAPI.useByPluginsConfig(pluginsConfig);
111
```
112

113
### initialize Method
114

115
Initializes all registered plugins and prepares them for use.
116

117
```javascript { .api }
118
/**
119
 * Initialize all registered plugins
120
 * Must be called after all plugins are registered
121
 * @returns void
122
 */
123
initialize(): void;
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Register all plugins first
130
app.pluginAPI
131
  .use("@vuepress/plugin-blog")
132
  .use("@vuepress/plugin-search");
133

134
// Then initialize the plugin system
135
app.pluginAPI.initialize();
136

137
// Access enabled plugins
138
console.log(`${app.pluginAPI.enabledPlugins.length} plugins enabled`);
139
```
140

141
### applySyncOption Method
142

143
Applies a synchronous plugin option to all registered plugins.
144

145
```javascript { .api }
146
/**
147
 * Apply synchronous plugin option
148
 * @param name - Option name
149
 * @param args - Arguments to pass to option handlers
150
 * @returns PluginAPI instance for chaining
151
 */
152
applySyncOption(name: string, ...args: any[]): PluginAPI;
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Apply chainWebpack option to modify webpack config
159
app.pluginAPI.applySyncOption("chainWebpack", webpackConfig, isServer);
160

161
// Apply extendMarkdown option to customize markdown processing
162
app.pluginAPI.applySyncOption("extendMarkdown", markdownIt);
163
```
164

165
### applyAsyncOption Method
166

167
Applies an asynchronous plugin option to all registered plugins.
168

169
```javascript { .api }
170
/**
171
 * Apply asynchronous plugin option
172
 * @param name - Option name
173
 * @param args - Arguments to pass to option handlers
174
 * @returns Promise that resolves when all handlers complete
175
 */
176
async applyAsyncOption(name: string, ...args: any[]): Promise<void>;
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
// Apply ready hook when app is ready
183
await app.pluginAPI.applyAsyncOption("ready");
184

185
// Apply generated hook after site generation
186
await app.pluginAPI.applyAsyncOption("generated", pages);
187

188
// Apply additionalPages to add dynamic pages
189
await app.pluginAPI.applyAsyncOption("additionalPages", app);
190
```
191

192
### getOption Method
193

194
Retrieves a specific plugin option handler.
195

196
```javascript { .api }
197
/**
198
 * Get existing plugin option
199
 * @param name - Option name
200
 * @returns Option instance
201
 */
202
getOption(name: string): Option;
203

204
interface Option {
205
  /** Option name */
206
  name: string;
207
  /** Registered handlers */
208
  items: OptionItem[];
209
  /** Applied values from handlers */
210
  appliedValues: any[];
211
  /** Apply option to all handlers */
212
  apply(...args: any[]): any;
213
}
214
```
215

216
**Usage Examples:**
217

218
```javascript
219
// Get chainWebpack option
220
const chainWebpackOption = app.pluginAPI.getOption("chainWebpack");
221
console.log(`${chainWebpackOption.items.length} chainWebpack handlers`);
222

223
// Get enhanceAppFiles option
224
const enhanceOption = app.pluginAPI.getOption("enhanceAppFiles");
225
enhanceOption.appliedValues.forEach(file => {
226
  console.log(`Enhance app file: ${file}`);
227
});
228
```
229

230
## Plugin Options
231

232
### Lifecycle Hooks
233

234
```javascript { .api }
235
interface LifecycleHooks {
236
  /** Called when app is ready */
237
  ready?: () => void | Promise<void>;
238
  
239
  /** Called after compilation */
240
  compiled?: () => void | Promise<void>;
241
  
242
  /** Called when files are updated (dev mode) */
243
  updated?: () => void | Promise<void>;
244
  
245
  /** Called after site generation */
246
  generated?: (pages: Page[]) => void | Promise<void>;
247
}
248
```
249

250
### Build Configuration Options  
251

252
```javascript { .api }
253
interface BuildOptions {
254
  /** Modify webpack configuration */
255
  chainWebpack?: (config: WebpackChainConfig, isServer: boolean) => void;
256
  
257
  /** Extend markdown processor */
258
  extendMarkdown?: (md: MarkdownIt) => void;
259
  
260
  /** Chain markdown configuration */
261
  chainMarkdown?: (config: any) => void;
262
  
263
  /** Global constants definition */
264
  define?: { [key: string]: any };
265
  
266
  /** Module aliases */
267
  alias?: { [key: string]: string };
268
}
269
```
270

271
### Client-Side Options
272

273
```javascript { .api }
274
interface ClientOptions {
275
  /** Client app enhancement files */
276
  enhanceAppFiles?: string[] | (() => string[] | Promise<string[]>);
277
  
278
  /** Client-side dynamic modules */
279
  clientDynamicModules?: () => string | Promise<string>;
280
  
281
  /** Client root mixin */
282
  clientRootMixin?: string;
283
  
284
  /** Global UI components */
285
  globalUIComponents?: string[] | string;
286
}
287
```
288

289
### Content Options
290

291
```javascript { .api }
292
interface ContentOptions {
293
  /** Additional pages to generate */
294
  additionalPages?: PageOptions[] | (() => PageOptions[] | Promise<PageOptions[]>);
295
  
296
  /** Extend page data */
297
  extendPageData?: (page: Page) => void | Promise<void>;
298
  
299
  /** Output files */
300
  outFiles?: { [path: string]: string };
301
}
302
```
303

304
### Development Options
305

306
```javascript { .api }
307
interface DevelopmentOptions {
308
  /** Before dev server setup */
309
  beforeDevServer?: (app: any, server: any) => void;
310
  
311
  /** After dev server setup */
312
  afterDevServer?: (app: any, server: any) => void;
313
  
314
  /** Extend CLI commands */
315
  extendCli?: (cli: any) => void;
316
}
317
```
318

319
## Plugin Development
320

321
### Basic Plugin Structure
322

323
```javascript { .api }
324
interface Plugin {
325
  /** Plugin name */
326
  name?: string;
327
  
328
  /** Allow multiple instances */
329
  multiple?: boolean;
330
  
331
  /** Child plugins */
332
  plugins?: PluginConfig[];
333
  
334
  /** Lifecycle hooks */
335
  ready?: () => void | Promise<void>;
336
  compiled?: () => void | Promise<void>;
337
  updated?: () => void | Promise<void>;
338
  generated?: (pages: Page[]) => void | Promise<void>;
339
  
340
  /** Build options */
341
  chainWebpack?: (config: any, isServer: boolean) => void;
342
  extendMarkdown?: (md: any) => void;
343
  define?: { [key: string]: any };
344
  alias?: { [key: string]: string };
345
  
346
  /** Content options */
347
  additionalPages?: any;
348
  extendPageData?: (page: Page) => void | Promise<void>;
349
  
350
  /** Client-side options */
351
  enhanceAppFiles?: string[] | (() => string[] | Promise<string[]>);
352
  clientDynamicModules?: () => string | Promise<string>;
353
  clientRootMixin?: string;
354
  globalUIComponents?: string[] | string;
355
  
356
  /** Development options */
357
  beforeDevServer?: (app: any, server: any) => void;
358
  afterDevServer?: (app: any, server: any) => void;
359
  
360
  /** Advanced hooks */
361
  chainMarkdown?: (config: any) => void;
362
  outFiles?: { [path: string]: string };
363
  
364
  /** Other custom options */
365
  [key: string]: any;
366
}
367
```
368

369
**Usage Examples:**
370

371
```javascript
372
// Simple plugin example
373
const myPlugin = {
374
  name: "my-custom-plugin",
375
  ready() {
376
    console.log("Plugin ready!");
377
  },
378
  extendMarkdown(md) {
379
    md.use(require("markdown-it-footnote"));
380
  },
381
  chainWebpack(config, isServer) {
382
    if (!isServer) {
383
      config.plugin("my-webpack-plugin")
384
        .use(require("my-webpack-plugin"));
385
    }
386
  },
387
};
388

389
app.pluginAPI.use(myPlugin);
390
```