0
# VitePress
1

2
VitePress is a Vite & Vue powered static site generator that combines modern development experience with powerful content authoring capabilities. It provides a fast development server with hot module replacement, static site generation for production, Vue-based theming system, and enhanced markdown processing with Vue component support.
3

4
## Package Information
5

6
- **Package Name**: vitepress
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vitepress`
10

11
## Core Imports
12

13
```typescript
14
import { defineConfig, build, createServer, serve } from "vitepress";
15
```
16

17
For client-side usage:
18

19
```typescript
20
import { useData, useRoute, useRouter, withBase } from "vitepress/client";
21
```
22

23
For theming:
24

25
```typescript
26
import DefaultTheme from "vitepress/theme";
27
```
28

29
CommonJS (Node.js APIs only):
30

31
```javascript
32
const { defineConfig, build, createServer, serve } = require("vitepress");
33
```
34

35
## Basic Usage
36

37
```typescript
38
// .vitepress/config.ts
39
import { defineConfig } from "vitepress";
40

41
export default defineConfig({
42
  title: "My Documentation Site",
43
  description: "A VitePress powered documentation site",
44
  themeConfig: {
45
    nav: [
46
      { text: "Guide", link: "/guide/" },
47
      { text: "API", link: "/api/" }
48
    ],
49
    sidebar: {
50
      "/guide/": [
51
        {
52
          text: "Introduction",
53
          items: [
54
            { text: "Getting Started", link: "/guide/getting-started" },
55
            { text: "Configuration", link: "/guide/configuration" }
56
          ]
57
        }
58
      ]
59
    }
60
  }
61
});
62

63
// Build for production
64
import { build } from "vitepress";
65
await build();
66

67
// Development server
68
import { createServer } from "vitepress";
69
const server = await createServer();
70
await server.listen();
71
```
72

73
## Architecture
74

75
VitePress is built around several key components:
76

77
- **Configuration System**: Type-safe configuration with `defineConfig` helpers supporting themes, markdown options, and site metadata
78
- **Development Server**: Vite-powered dev server with HMR, Vue component support in markdown, and fast rebuilds
79
- **Build System**: Static site generation with optimized bundle splitting, pre-rendering, and SEO-friendly output
80
- **Theming Engine**: Vue-based theme system with default theme components, composables for state management, and full customization support
81
- **Markdown Processor**: Enhanced markdown with Vue component embedding, syntax highlighting, custom containers, and frontmatter processing
82
- **Client Runtime**: SPA-like navigation with data loading, routing utilities, and reactive state management
83

84
## Capabilities
85

86
### Configuration Management
87

88
Type-safe configuration system with helper functions and comprehensive theme configuration options. Supports extending configurations, multi-locale setups, and Vite integration.
89

90
```typescript { .api }
91
function defineConfig<ThemeConfig = any>(
92
  config: UserConfig<ThemeConfig>
93
): UserConfig<ThemeConfig>;
94

95
function resolveConfig(
96
  root?: string,
97
  command?: "serve" | "build",
98
  mode?: string
99
): Promise<SiteConfig>;
100

101
interface UserConfig<ThemeConfig = any> {
102
  extends?: UserConfig<ThemeConfig>;
103
  base?: string;
104
  title?: string;
105
  description?: string;
106
  themeConfig?: ThemeConfig;
107
  markdown?: MarkdownOptions;
108
  vite?: UserConfig;
109
  locales?: LocaleConfig<ThemeConfig>;
110
}
111
```
112

113
[Configuration](./configuration.md)
114

115
### Build and Development
116

117
Build system for production static sites and development server with hot reloading. Includes preview server for testing built sites and various build optimization options.
118

119
```typescript { .api }
120
function build(
121
  root?: string,
122
  buildOptions?: BuildOptions
123
): Promise<void>;
124

125
function createServer(
126
  root?: string,
127
  serverOptions?: ServerOptions
128
): Promise<ViteDevServer>;
129

130
function serve(options?: ServeOptions): Promise<void>;
131

132
interface BuildOptions {
133
  base?: string;
134
  outDir?: string;
135
  mpa?: boolean;
136
}
137
```
138

139
[Build and Development](./build-dev.md)
140

141
### Client-Side API
142

143
Client-side composables and utilities for accessing VitePress runtime data, navigation, and page information. Essential for custom themes and Vue components in markdown.
144

145
```typescript { .api }
146
function useData<T = any>(): VitePressData<T>;
147
function useRouter(): Router;
148
function useRoute(): Route;
149
function withBase(path: string): string;
150

151
interface VitePressData<T> {
152
  site: Ref<SiteData<T>>;
153
  page: Ref<PageData>;
154
  theme: Ref<T>;
155
  frontmatter: Ref<Record<string, any>>;
156
  title: Ref<string>;
157
  description: Ref<string>;
158
  isDark: Ref<boolean>;
159
}
160
```
161

162
[Client-Side API](./client-api.md)
163

164
### Theme System
165

166
Vue-based theming with default theme components, sidebar and navigation management, and comprehensive customization options. Includes composables for theme state and UI components.
167

168
```typescript { .api }
169
interface Theme {
170
  Layout?: Component;
171
  enhanceApp?: (ctx: EnhanceAppContext) => void;
172
  extends?: Theme;
173
}
174

175
interface EnhanceAppContext {
176
  app: App;
177
  router: Router;
178
  siteData: Ref<SiteData>;
179
}
180

181
// Default theme composables
182
function useSidebar(): DefaultTheme.DocSidebar;
183
function useLocalNav(): DefaultTheme.DocLocalNav;
184
```
185

186
[Theme System](./theming.md)
187

188
### Markdown Processing
189

190
Enhanced markdown processing with Vue component support, syntax highlighting, custom containers, and frontmatter parsing. Includes extensible plugin system and custom renderers.
191

192
```typescript { .api }
193
function createMarkdownRenderer(
194
  options?: MarkdownOptions,
195
  base?: string,
196
  logger?: Logger
197
): MarkdownIt;
198

199
interface MarkdownOptions {
200
  lineNumbers?: boolean;
201
  config?: (md: MarkdownIt) => void;
202
  theme?: ThemeOptions;
203
  languages?: LanguageInput[];
204
  externalLinks?: Record<string, string>;
205
}
206
```
207

208
[Markdown Processing](./markdown.md)
209

210
### Command-Line Interface
211

212
Complete CLI for project initialization, development, building, and preview. Supports various options for customization and deployment workflows.
213

214
```typescript { .api }
215
// CLI commands
216
vitepress [dev] [root]     // Start development server
217
vitepress build [root]     // Build for production  
218
vitepress preview [root]   // Preview built site
219
vitepress init [root]      // Initialize new project
220

221
// Programmatic CLI access
222
function init(root?: string): Promise<void>;
223
function scaffold(options: ScaffoldOptions): string;
224
```
225

226
[Command-Line Interface](./cli.md)
227

228
## Types
229

230
```typescript { .api }
231
interface SiteData<ThemeConfig = any> {
232
  base: string;
233
  lang: string;
234
  title: string;
235
  description: string;
236
  head: HeadConfig[];
237
  themeConfig: ThemeConfig;
238
  locales: LocaleConfig<ThemeConfig>;
239
  appearance: boolean | string | object;
240
  router: { prefetchLinks: boolean };
241
}
242

243
interface PageData {
244
  title: string;
245
  description: string;
246
  relativePath: string;
247
  headers: Header[];
248
  frontmatter: Record<string, any>;
249
  lastUpdated?: number;
250
}
251

252
interface Header {
253
  level: number;
254
  title: string;
255
  slug: string;
256
  link: string;
257
  children: Header[];
258
}
259

260
type HeadConfig = 
261
  | [string, Record<string, string>] 
262
  | [string, Record<string, string>, string];
263

264
type LocaleConfig<ThemeConfig = any> = Record<
265
  string, 
266
  LocaleSpecificConfig<ThemeConfig> & { 
267
    label: string; 
268
    link?: string; 
269
  }
270
>;
271

272
type Awaitable<T> = T | PromiseLike<T>;
273
```