0
# TypeDoc Plugin Markdown
1

2
TypeDoc Plugin Markdown is a plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown format. It extends TypeDoc's functionality by providing custom themes and output formats specifically designed for Markdown-based documentation systems, allowing developers to generate comprehensive API documentation from TypeScript source code while outputting clean, structured Markdown files.
3

4
## Package Information
5

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

11
## Core Imports
12

13
The plugin is primarily used via TypeDoc's plugin system, but also exports public API components for customization:
14

15
```typescript
16
// Main plugin function (for programmatic use)
17
import { load } from "typedoc-plugin-markdown";
18

19
// Public API components for customization
20
import { 
21
  MarkdownTheme, 
22
  MarkdownThemeContext,
23
  MarkdownPageEvent,
24
  MarkdownRendererEvent,
25
  MemberRouter,
26
  ModuleRouter
27
} from "typedoc-plugin-markdown";
28
```
29

30
Most commonly, the plugin is used via TypeDoc configuration without direct imports:
31

32
```json
33
{
34
  "plugin": ["typedoc-plugin-markdown"],
35
  "markdown": "./docs"
36
}
37
```
38

39
## Basic Usage
40

41
**CLI Usage (Most Common):**
42

43
```bash
44
# Install TypeDoc and the plugin
45
npm install --save-dev typedoc typedoc-plugin-markdown
46

47
# Generate markdown documentation
48
npx typedoc --plugin typedoc-plugin-markdown --markdown ./docs src/**/*.ts
49
```
50

51
**Configuration File Usage:**
52

53
```json
54
// typedoc.json
55
{
56
  "plugin": ["typedoc-plugin-markdown"],
57
  "markdown": "./docs",
58
  "entryPoints": ["src/**/*.ts"],
59
  "fileExtension": ".md",
60
  "useCodeBlocks": true
61
}
62
```
63

64
**Programmatic Usage:**
65

66
```typescript
67
import { Application } from "typedoc";
68
import { load } from "typedoc-plugin-markdown";
69

70
// Bootstrap the plugin with TypeDoc
71
const app = new Application();
72
load(app);
73

74
// Configure for markdown output
75
app.options.setValue('plugin', ['typedoc-plugin-markdown']);
76
app.options.setValue('markdown', './docs');
77

78
// Generate documentation
79
const project = app.converter.convert([
80
  app.expandInputFiles(['src/**/*.ts'])
81
]);
82

83
if (project) {
84
  await app.generateDocs(project, './docs');
85
}
86
```
87

88
## Architecture
89

90
TypeDoc Plugin Markdown is built around several key components:
91

92
- **Plugin Bootstrap**: The `load()` function integrates with TypeDoc's plugin system, adding markdown-specific options and output handlers
93
- **Theme System**: `MarkdownTheme` and `MarkdownThemeContext` control how TypeDoc models are mapped to files and rendered as markdown
94
- **Router System**: Multiple router implementations (`MemberRouter`, `ModuleRouter`) provide different file organization strategies
95
- **Event System**: `MarkdownPageEvent` and `MarkdownRendererEvent` enable hooking into the rendering lifecycle
96
- **Customization Framework**: Comprehensive options system with 66+ configuration settings for controlling output format and behavior
97

98
## Capabilities
99

100
### Plugin Bootstrap
101

102
Core plugin initialization that integrates with TypeDoc's application lifecycle, adding markdown output capabilities and configuration options.
103

104
```typescript { .api }
105
/**
106
 * The function that is called by TypeDoc to bootstrap the plugin.
107
 * Exposes additional TypeDoc options and makes adjustments for markdown output.
108
 */
109
function load(app: Application): void;
110
```
111

112
[Plugin Bootstrap](./plugin-bootstrap.md)
113

114
### Theme System
115

116
Custom theme implementation that controls how TypeDoc models are rendered as markdown files, with complete customization support and navigation building.
117

118
```typescript { .api }
119
class MarkdownTheme extends Theme {
120
  constructor(renderer: Renderer);
121
  render(page: MarkdownPageEvent): string;
122
  getNavigation(project: ProjectReflection): NavigationItem[];
123
}
124

125
class MarkdownThemeContext {
126
  readonly theme: MarkdownTheme;
127
  readonly page: MarkdownPageEvent<Reflection>;
128
  readonly options: Options;
129
  templates: any;
130
  partials: any;
131
  helpers: any;
132
}
133

134
class NavigationBuilder {
135
  constructor(router: Router, theme: MarkdownTheme, project: ProjectReflection);
136
  getNavigation(): NavigationItem[];
137
}
138
```
139

140
[Theme System](./theme-system.md)
141

142
### Routing and File Organization
143

144
Multiple router implementations providing different strategies for organizing generated documentation files, built on the MarkdownRouter base class.
145

146
```typescript { .api }
147
abstract class MarkdownRouter extends BaseRouter {
148
  abstract buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
149
  abstract getIdealBaseName(reflection: Reflection): string;
150
  buildPages(project: ProjectReflection): PageDefinition[];
151
  getAnchor(target: RouterTarget): string;
152
}
153

154
class MemberRouter extends MarkdownRouter {
155
  buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
156
  getIdealBaseName(reflection: Reflection): string;
157
}
158

159
class ModuleRouter extends MarkdownRouter {
160
  buildChildPages(reflection: Reflection, outPages: PageDefinition[]): void;
161
  getIdealBaseName(reflection: Reflection): string;
162
}
163
```
164

165
[Routing System](./routing-system.md)
166

167
### Events and Lifecycle Hooks
168

169
Event system for hooking into the markdown generation lifecycle, enabling customization at various rendering stages.
170

171
```typescript { .api }
172
class MarkdownPageEvent<out Model extends RouterTarget = RouterTarget> {
173
  readonly model: Model;
174
  project: ProjectReflection;
175
  filename: string;
176
  url: string;
177
  contents: string;
178
  static readonly BEGIN = 'beginPage';
179
  static readonly END = 'endPage';
180
}
181

182
class MarkdownRendererEvent {
183
  readonly project: ProjectReflection;
184
  readonly outputDirectory: string;
185
  pages: PageDefinition[];
186
  navigation?: NavigationItem[];
187
  static readonly BEGIN = 'beginRender';
188
  static readonly END = 'endRender';
189
}
190
```
191

192
[Events and Hooks](./events-hooks.md)
193

194
### Configuration Options
195

196
Comprehensive configuration system with 66+ options for customizing markdown output, file organization, and formatting.
197

198
```typescript { .api }
199
interface PluginOptions {
200
  anchorPrefix?: string;
201
  fileExtension?: string;
202
  entryFileName?: string;
203
  modulesFileName?: string;
204
  flattenOutputFiles?: boolean;
205
  hidePageHeader?: boolean;
206
  hidePageTitle?: boolean;
207
  hideBreadcrumbs?: boolean;
208
  mergeReadme?: boolean;
209
  useCodeBlocks?: boolean;
210
  useHTMLAnchors?: boolean;
211
  membersWithOwnFile?: Array<string>;
212
  indexFormat?: 'list' | 'table' | 'htmlTable';
213
  interfacePropertiesFormat?: 'list' | 'table' | 'htmlTable';
214
  classPropertiesFormat?: 'list' | 'table' | 'htmlTable';
215
  enumMembersFormat?: 'list' | 'table' | 'htmlTable';
216
  parametersFormat?: 'list' | 'table' | 'htmlTable';
217
  // ... 50+ more configuration options
218
}
219
```
220

221
[Configuration Options](./configuration-options.md)
222

223
## Types
224

225
### Core Application Types
226

227
```typescript { .api }
228
interface MarkdownApplication extends Application {
229
  renderer: MarkdownRenderer & Renderer;
230
}
231

232
interface MarkdownRenderer extends Renderer {
233
  markdownHooks: EventHooks<MarkdownRendererHooks, string>;
234
  preRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
235
  postRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
236
  packagesMeta: Record<string, PackageMetaData>;
237
}
238
```
239

240
### Navigation and Theme Types
241

242
```typescript { .api }
243
interface NavigationItem {
244
  title: string;
245
  path?: string | null;
246
  kind?: ReflectionKind;
247
  isDeprecated?: boolean;
248
  children?: NavigationItem[];
249
}
250

251
interface PackageMetaData {
252
  description: string;
253
  options: Options;
254
}
255

256
type RenderTemplate<T> = (data: T) => string;
257
type MemberSection = ReflectionGroup | ReflectionCategory;
258
```
259

260
### Hook System Types
261

262
```typescript { .api }
263
interface MarkdownRendererHooks {
264
  ['page.begin']: [MarkdownThemeContext];
265
  ['page.end']: [MarkdownThemeContext];
266
  ['content.begin']: [MarkdownThemeContext];
267
  ['index.page.begin']: [MarkdownThemeContext];
268
  ['index.page.end']: [MarkdownThemeContext];
269
}
270
```