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
```