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)