0
# VuePress
1
2
VuePress is a minimalistic Vue.js-based documentation generator that provides comprehensive functionality for building and serving documentation sites. It features Vue component-based layout systems, markdown processing with custom containers, theming, and an extensive plugin architecture for creating rich, interactive documentation.
3
4
## Package Information
5
6
- **Package Name**: vuepress
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install vuepress`
10
11
## Core Imports
12
13
```javascript
14
const { createApp, dev, build, eject, version } = require("vuepress");
15
```
16
17
For ES modules:
18
19
```javascript
20
import { createApp, dev, build, eject, version } from "vuepress";
21
```
22
23
## Basic Usage
24
25
```javascript
26
const { createApp, dev, build } = require("vuepress");
27
28
// Create a VuePress application
29
const app = createApp({
30
sourceDir: "./docs",
31
plugins: [
32
["@vuepress/plugin-blog"],
33
],
34
themeConfig: {
35
nav: [
36
{ text: "Home", link: "/" },
37
{ text: "Guide", link: "/guide/" },
38
],
39
},
40
});
41
42
// Development server
43
async function startDev() {
44
await dev({
45
sourceDir: "./docs",
46
theme: "@vuepress/theme-default",
47
});
48
}
49
50
// Production build
51
async function buildSite() {
52
await build({
53
sourceDir: "./docs",
54
dest: "./dist",
55
});
56
}
57
```
58
59
## Architecture
60
61
VuePress is built around several key components:
62
63
- **App Class**: Central orchestrator managing configuration, pages, plugins, and build processes
64
- **Plugin System**: Extensible architecture with hooks for customizing build, markdown processing, and client behavior
65
- **Page Management**: Automatic discovery and processing of markdown and Vue files into routable pages
66
- **Build Pipeline**: Webpack-driven development and production build processes with hot module replacement
67
- **Theme Integration**: Flexible theming system with component-based layouts and styling
68
- **CLI Interface**: Command-line interface for development and build operations
69
- **DevProcess/BuildProcess**: Specialized process management for development server and production builds
70
71
## Capabilities
72
73
### Core API Functions
74
75
Main entry point functions for creating and operating VuePress applications.
76
77
```javascript { .api }
78
/**
79
* Creates a VuePress application instance
80
* @param options - Application configuration options
81
* @returns App instance
82
*/
83
function createApp(options: AppOptions): App;
84
85
/**
86
* Starts development server with hot module replacement
87
* @param options - Development server configuration
88
* @returns Promise resolving to App instance
89
*/
90
function dev(options: DevOptions): Promise<App>;
91
92
/**
93
* Builds the site for production
94
* @param options - Build configuration
95
* @returns Promise resolving to App instance
96
*/
97
function build(options: BuildOptions): Promise<App>;
98
99
/**
100
* Ejects default theme files to local project
101
* @param dir - Target directory for ejected theme
102
* @returns Promise
103
*/
104
function eject(dir: string): Promise<void>;
105
106
/** Package version string */
107
const version: string;
108
```
109
110
[Core API](./core-api.md)
111
112
### Application Management
113
114
App class providing comprehensive site orchestration, configuration management, and build coordination.
115
116
```javascript { .api }
117
class App {
118
constructor(options: AppOptions);
119
120
/** Process configuration, plugins, and prepare for build/dev */
121
process(): Promise<void>;
122
123
/** Launch development server */
124
dev(): Promise<App>;
125
126
/** Build static site */
127
build(): Promise<App>;
128
129
/** Add page to site */
130
addPage(options: PageOptions): Promise<void>;
131
132
/** Get site data for client */
133
getSiteData(): SiteData;
134
135
/** Get file path within core library */
136
getLibFilePath(relative: string): string;
137
}
138
```
139
140
[Application Management](./app-management.md)
141
142
### Plugin System
143
144
Comprehensive plugin architecture with hooks for customizing every aspect of the build process.
145
146
```javascript { .api }
147
class PluginAPI {
148
/** Register a plugin */
149
use(pluginRaw: string | Plugin, pluginOptions?: any): PluginAPI;
150
151
/** Initialize all registered plugins */
152
initialize(): void;
153
154
/** Apply synchronous plugin option */
155
applySyncOption(name: string, ...args: any[]): PluginAPI;
156
157
/** Apply asynchronous plugin option */
158
applyAsyncOption(name: string, ...args: any[]): Promise<void>;
159
}
160
```
161
162
[Plugin System](./plugin-system.md)
163
164
### Page Management
165
166
Page class representing individual documents with frontmatter processing, header extraction, and permalink generation.
167
168
```javascript { .api }
169
class Page {
170
constructor(options: PageOptions, context: App);
171
172
/** Process page content and metadata */
173
process(options: ProcessOptions): Promise<void>;
174
175
/** Serialize page metadata for client */
176
toJson(): object;
177
178
/** Page properties */
179
readonly title: string;
180
readonly path: string;
181
readonly frontmatter: object;
182
readonly headers: Header[];
183
}
184
```
185
186
[Page Management](./page-management.md)
187
188
### Build Processes
189
190
DevProcess and BuildProcess classes providing specialized process management for development server and production builds.
191
192
```javascript { .api }
193
class DevProcess {
194
constructor(context: App);
195
196
/** Prepare development server configuration */
197
process(): Promise<DevProcess>;
198
199
/** Create webpack dev server instance */
200
createServer(): DevProcess;
201
202
/** Start the development server */
203
listen(callback?: () => void): DevProcess;
204
}
205
206
class BuildProcess {
207
constructor(context: App);
208
209
/** Prepare build configuration */
210
process(): Promise<void>;
211
212
/** Compile and render all pages */
213
render(): Promise<void>;
214
}
215
```
216
217
[Build Processes](./build-processes.md)
218
219
## Types and Configuration
220
221
Common types and interfaces used throughout the VuePress API.
222
223
```javascript { .api }
224
interface AppOptions {
225
sourceDir?: string;
226
plugins?: PluginConfig[];
227
theme?: string | ThemeConfig;
228
temp?: string;
229
dest?: string;
230
siteConfig?: SiteConfig;
231
}
232
233
interface SiteConfig {
234
title?: string;
235
description?: string;
236
base?: string;
237
head?: HeadTag[];
238
themeConfig?: any;
239
markdown?: MarkdownConfig;
240
patterns?: string[];
241
}
242
```
243
244
[Types and Configuration](./types-configuration.md)