0
# TypeDoc VitePress Theme
1
2
TypeDoc VitePress Theme is a specialized TypeDoc theme that extends typedoc-plugin-markdown to generate Markdown output specifically formatted for VitePress static site generators. It serves as a bridge between TypeDoc's API documentation generation capabilities and VitePress's Markdown-based documentation system, enabling developers to automatically generate comprehensive API documentation that seamlessly integrates with VitePress sites.
3
4
## Package Information
5
6
- **Package Name**: typedoc-vitepress-theme
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install typedoc-vitepress-theme`
10
- **Peer Dependencies**: `typedoc-plugin-markdown >=4.4.0`
11
12
## Core Imports
13
14
```typescript
15
import { load } from "typedoc-vitepress-theme";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { load } = require("typedoc-vitepress-theme");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import { MarkdownApplication } from "typedoc-plugin-markdown";
28
import { load } from "typedoc-vitepress-theme";
29
30
// Load the plugin into a TypeDoc application
31
const app = new MarkdownApplication();
32
load(app);
33
34
// Plugin automatically configures options and event handlers
35
// No additional setup required
36
```
37
38
## Architecture
39
40
The TypeDoc VitePress Theme is built around several key components:
41
42
- **Plugin Loader**: Main `load` function that registers the theme with TypeDoc
43
- **Options System**: Configurable options for VitePress integration and sidebar generation
44
- **Sidebar Generation**: Multiple format support (VitePress, VuePress 1.x, VuePress 2.x)
45
- **URL Processing**: Anchor slug formatting and link processing for VitePress compatibility
46
- **Event Handling**: Post-processing of generated markdown for VitePress optimization
47
48
## Capabilities
49
50
### Plugin Loading
51
52
Main entry point function that registers the theme with a TypeDoc markdown application instance.
53
54
```typescript { .api }
55
/**
56
* Load the VitePress theme plugin into a TypeDoc markdown application
57
* @param app - TypeDoc markdown application instance
58
*/
59
function load(app: MarkdownApplication): void;
60
```
61
62
**Required Import:**
63
```typescript
64
import { MarkdownApplication } from "typedoc-plugin-markdown";
65
```
66
67
The `load` function performs the following operations when called:
68
69
1. **Registers Plugin Options**: Adds configuration options for VitePress integration
70
- `docsRoot`: Path to VitePress project root directory
71
- `sidebar`: Configuration for autogenerated VitePress sidebar
72
73
2. **Sets Default Presets**: Applies optimal TypeDoc settings for VitePress:
74
- `hidePageHeader: true` - Removes page headers from generated markdown
75
- `entryFileName: "index.md"` - Uses index.md as entry file name
76
- `out: "./api"` - Sets default output directory
77
78
3. **Configures Event Handlers**: Sets up post-processing for VitePress compatibility:
79
- Processes internal links to ensure proper anchor formatting
80
- Applies VitePress-compatible URL slugification to anchor links
81
82
4. **Enables Sidebar Generation**: Automatically generates sidebar configuration files:
83
- Creates `typedoc-sidebar.json` with navigation structure
84
- Supports multiple formats: VitePress, VuePress 1.x, VuePress 2.x
85
- Configurable output formatting and collapsible behavior
86
87
## Types
88
89
The plugin defines the following TypeScript interfaces for configuration:
90
91
```typescript { .api }
92
interface PluginOptions {
93
/**
94
* The path to the VitePress project root.
95
*/
96
docsRoot: string;
97
98
/**
99
* Configures the autogenerated VitePress sidebar.
100
*/
101
sidebar: Sidebar;
102
}
103
104
interface Sidebar {
105
/** Enable/disable automatic sidebar generation */
106
autoConfiguration: boolean;
107
/** Sidebar format - "vitepress", "vuepress1", or "vuepress2" */
108
format: string;
109
/** Pretty format the sidebar JSON output */
110
pretty: boolean;
111
/** Determines if sidebar items with children are collapsed by default */
112
collapsed: boolean;
113
}
114
```
115
116
## Configuration Options
117
118
The plugin automatically registers the following TypeDoc options that can be configured in your `typedoc.json`:
119
120
### docsRoot Option
121
122
Specifies the path to the VitePress project root directory. Required when TypeDoc runs from outside the VitePress project root.
123
124
```json
125
{
126
"docsRoot": "./docs"
127
}
128
```
129
130
**Use Case Example:**
131
```
132
├── package.json
133
├── typedoc.json # TypeDoc runs from here
134
└── docs/ # VitePress root (set as docsRoot)
135
├── .vitepress/
136
└── api/ # TypeDoc output directory
137
└── index.md
138
```
139
140
### sidebar Option
141
142
Configures the autogenerated VitePress sidebar with the following properties:
143
144
- `autoConfiguration` (boolean): Enable/disable automatic sidebar generation (default: true)
145
- `format` (string): Sidebar format - "vitepress", "vuepress1", or "vuepress2" (default: "vitepress")
146
- `pretty` (boolean): Pretty format the sidebar JSON output (default: false)
147
- `collapsed` (boolean): Determines if sidebar items with children are collapsed by default (default: true)
148
149
```json
150
{
151
"sidebar": {
152
"autoConfiguration": true,
153
"format": "vitepress",
154
"pretty": true,
155
"collapsed": false
156
}
157
}
158
```
159
160
## Configuration Examples
161
162
### Basic VitePress Configuration
163
164
```json
165
{
166
"out": "./docs/api",
167
"docsRoot": "./docs"
168
}
169
```
170
171
### Custom Sidebar Configuration
172
173
```json
174
{
175
"out": "./docs/api",
176
"docsRoot": "./docs",
177
"sidebar": {
178
"autoConfiguration": true,
179
"format": "vitepress",
180
"pretty": true,
181
"collapsed": false
182
}
183
}
184
```
185
186
### VuePress Compatibility
187
188
For VuePress 2.x projects:
189
```json
190
{
191
"out": "./docs/api",
192
"docsRoot": "./docs",
193
"sidebar": {
194
"autoConfiguration": true,
195
"format": "vuepress2",
196
"pretty": true,
197
"collapsed": true
198
}
199
}
200
```
201
202
For VuePress 1.x projects:
203
```json
204
{
205
"out": "./docs/api",
206
"docsRoot": "./docs",
207
"sidebar": {
208
"autoConfiguration": true,
209
"format": "vuepress1",
210
"pretty": true,
211
"collapsed": true
212
}
213
}
214
```
215
216
## Integration Notes
217
218
### File Structure Requirements
219
220
When using the plugin, ensure your project structure accommodates the VitePress configuration:
221
222
```
223
├── package.json
224
├── typedoc.json
225
└── docs/
226
├── .vitepress/
227
└── api/ # Generated by TypeDoc
228
├── index.md
229
└── typedoc-sidebar.json
230
```
231
232
### Generated Files
233
234
The plugin automatically generates:
235
236
- **API Documentation**: Markdown files compatible with VitePress
237
- **Sidebar Configuration**: `typedoc-sidebar.json` file containing navigation structure
238
- **Optimized Links**: Processed internal links with proper anchor formatting
239
240
### Usage in TypeDoc Configuration
241
242
Complete example of using the plugin in a TypeDoc configuration:
243
244
```json
245
{
246
"entryPoints": ["./src/index.ts"],
247
"out": "./docs/api",
248
"docsRoot": "./docs",
249
"plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
250
"sidebar": {
251
"autoConfiguration": true,
252
"format": "vitepress",
253
"pretty": true,
254
"collapsed": false
255
}
256
}
257
```
258
259
### VitePress Integration
260
261
To integrate the generated documentation into your VitePress site:
262
263
1. **Install the plugin**: `npm install typedoc-vitepress-theme`
264
2. **Configure TypeDoc**: Add the plugin to your `typedoc.json`
265
3. **Run TypeDoc**: Generate the API documentation
266
4. **Include in VitePress**: Reference the generated `typedoc-sidebar.json` in your VitePress configuration
267
268
Example VitePress config integration:
269
```javascript
270
import sidebarConfig from './api/typedoc-sidebar.json';
271
272
export default {
273
themeConfig: {
274
sidebar: {
275
'/api/': sidebarConfig
276
}
277
}
278
}
279
```