0
# TypeDoc
1

2
TypeDoc is a comprehensive documentation generator specifically designed for TypeScript projects that automatically creates API documentation from TypeScript source code and JSDoc comments. It provides extensive customization options including multiple output formats, configurable themes, support for monorepos and workspaces, and deep integration with TypeScript's type system to generate rich, navigable documentation.
3

4
## Package Information
5

6
- **Package Name**: typedoc
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install typedoc`
10
- **Peer Dependencies**: `typescript` (5.0.x - 5.9.x)
11

12
## Core Imports
13

14
```typescript
15
import { Application } from "typedoc";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Application } = require("typedoc");
22
```
23

24
### Entry Point Exports
25

26
```typescript
27
// Main entry point
28
import { Application, Models, Configuration } from "typedoc";
29

30
// Browser-compatible subset
31
import * as TypeDocBrowser from "typedoc/browser";
32

33
// Model types only
34
import * as Models from "typedoc/models";
35

36
// Debug utilities (unstable API)
37
import { debugReflectionLifetimes, debugRendererUrls } from "typedoc/debug";
38
```
39

40
## Basic Usage
41

42
```typescript
43
import { Application } from "typedoc";
44

45
// Create TypeDoc application
46
const app = await Application.bootstrapWithPlugins({
47
  entryPoints: ["src/index.ts"],
48
  out: "docs",
49
  theme: "default",
50
});
51

52
// Convert TypeScript project to documentation
53
const project = await app.convert();
54

55
if (project) {
56
  // Generate HTML documentation
57
  await app.generateDocs(project, "docs");
58
  
59
  // Or generate JSON output
60
  await app.generateJson(project, "docs/api.json");
61
}
62
```
63

64
## CLI Usage
65

66
TypeDoc provides a comprehensive command-line interface:
67

68
```bash
69
# Basic documentation generation
70
typedoc src/index.ts
71

72
# With custom output directory and theme
73
typedoc --out docs --theme default src/
74

75
# Generate JSON output
76
typedoc --json docs/api.json src/
77

78
# Watch mode for development
79
typedoc --watch src/
80
```
81

82
## Architecture
83

84
TypeDoc is built around several key components:
85

86
- **Application**: Core orchestrator managing the entire documentation generation process
87
- **Converter**: Transforms TypeScript source code and symbols into reflection objects  
88
- **Models**: Rich object model representing all documentation elements (reflections, types, comments)
89
- **Output System**: Renders documentation from reflections to various formats (HTML, JSON)
90
- **Configuration**: Comprehensive options system supporting multiple configuration sources
91
- **Serialization**: Converts reflections to/from JSON for storage and processing
92
- **Internationalization**: Multi-language support for documentation output
93

94
## Capabilities
95

96
### Application Management
97

98
Core application orchestration for TypeDoc documentation generation, including bootstrapping, plugin loading, and conversion coordination.
99

100
```typescript { .api }
101
class Application extends AbstractComponent<Application, ApplicationEvents> {
102
  readonly options: Options;
103
  readonly converter: Converter;
104
  readonly renderer: Renderer;
105
  readonly serializer: Serializer;
106
  readonly internationalization: Internationalization;
107
  readonly logger: Logger;
108

109
  static bootstrap(options?: Partial<TypeDocOptions>): Promise<Application>;
110
  static bootstrapWithPlugins(
111
    options: Partial<TypeDocOptions>,
112
    readers: OptionsReader[]
113
  ): Promise<Application>;
114
  
115
  convert(): Promise<ProjectReflection | undefined>;
116
  convertAndWatch(success: (project: ProjectReflection) => Promise<void>): Promise<never>;
117
  generateDocs(project: ProjectReflection, out: string): Promise<void>;
118
  generateJson(project: ProjectReflection, out: string): Promise<void>;
119
  validate(project: ProjectReflection): void;
120
}
121
```
122

123
[Application Management](./application.md)
124

125
### Documentation Models
126

127
Complete object model representing TypeScript documentation elements including reflections, types, comments, and source references.
128

129
```typescript { .api }
130
// Core reflection types
131
abstract class Reflection {
132
  readonly id: ReflectionId;
133
  readonly name: string;
134
  readonly kind: ReflectionKind;
135
  readonly flags: ReflectionFlag;
136
  comment?: Comment;
137
  readonly parent?: Reflection;
138
}
139

140
class ProjectReflection extends ContainerReflection {
141
  readonly packageVersion?: string;
142
  readonly readme?: string;
143
  readonly changelog?: string;
144
}
145

146
class DeclarationReflection extends ContainerReflection {
147
  type?: Type;
148
  defaultValue?: string;
149
  overwrites?: ReferenceType;
150
  inheritedFrom?: ReferenceType;
151
  implementationOf?: ReferenceType;
152
  extendedTypes?: Type[];
153
  extendedBy?: ReferenceType[];
154
  implementedTypes?: Type[];
155
  implementedBy?: ReferenceType[];
156
}
157

158
// Type system
159
abstract class Type {
160
  abstract readonly type: keyof TypeKindMap;
161
  toString(): string;
162
  visit<T>(visitor: TypeVisitor<T>): T;
163
}
164
```
165

166
[Documentation Models](./models.md)
167

168
### TypeScript Conversion
169

170
Converter system that transforms TypeScript source code, symbols, and AST nodes into TypeDoc's reflection model.
171

172
```typescript { .api }
173
class Converter extends AbstractComponent<Application, ConverterEvents> {
174
  convert(entryPoints: readonly DocumentationEntryPoint[]): ProjectReflection | undefined;
175
  convertSymbol(context: Context, symbol: ts.Symbol): Reflection | undefined;
176
}
177

178
class Context {
179
  readonly program: ts.Program;
180
  readonly project: ProjectReflection;
181
  readonly scope: Reflection;
182
  
183
  createDeclarationReflection(
184
    kind: ReflectionKind,
185
    symbol?: ts.Symbol,
186
    exportSymbol?: ts.Symbol,
187
    name?: string
188
  ): DeclarationReflection;
189
  
190
  finalizeDeclarationReflection(reflection: DeclarationReflection): void;
191
}
192
```
193

194
[TypeScript Conversion](./converter.md)
195

196
### Configuration System
197

198
Comprehensive configuration management supporting multiple option sources, type-safe declarations, and validation.
199

200
```typescript { .api }
201
class Options extends EventDispatcher<OptionsEvents, EventsWithArgument> {
202
  addDeclaration(declaration: DeclarationOption): void;
203
  getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptions[K];
204
  setValue<K extends keyof TypeDocOptions>(name: K, value: TypeDocOptions[K]): void;
205
  isSet(name: keyof TypeDocOptions): boolean;
206
  read(logger: Logger): void;
207
}
208

209
// Option readers
210
class ArgumentsReader implements OptionsReader {
211
  constructor(priority: number);
212
  read(container: Options, logger: Logger, cwd: string): void;
213
}
214

215
class TypeDocReader implements OptionsReader {
216
  read(container: Options, logger: Logger, cwd: string): void;
217
}
218

219
class TSConfigReader implements OptionsReader {
220
  read(container: Options, logger: Logger, cwd: string): void;
221
}
222
```
223

224
[Configuration System](./configuration.md)
225

226
### Output and Rendering
227

228
Output generation system including themes, renderers, routing, and multiple output formats with extensive customization options.
229

230
```typescript { .api }
231
class Renderer extends AbstractComponent<Application, RendererEvents> {
232
  render(project: ProjectReflection, outputDirectory: string): Promise<void>;
233
  renderDocument(page: PageEvent<Reflection>): string;
234
}
235

236
abstract class Theme {
237
  abstract render(page: PageEvent<Reflection>, template: RenderTemplate<PageEvent<Reflection>>): string;
238
  abstract getUrls(project: ProjectReflection): UrlMapping[];
239
  abstract getNavigation(project: ProjectReflection): NavigationElement;
240
}
241

242
class DefaultTheme extends Theme {
243
  render(page: PageEvent<Reflection>, template: RenderTemplate<PageEvent<Reflection>>): string;
244
  getUrls(project: ProjectReflection): UrlMapping[];
245
  getNavigation(project: ProjectReflection): NavigationElement;
246
}
247
```
248

249
[Output and Rendering](./output.md)
250

251
### JSON Serialization
252

253
Serialization system for converting reflections to/from JSON format, enabling data exchange and custom processing workflows.
254

255
```typescript { .api }
256
class Serializer extends AbstractComponent<Application, SerializerEvents> {
257
  projectToObject(project: ProjectReflection, out: string): JSONOutput.ProjectReflection;
258
  toObject(value: unknown): unknown;
259
}
260

261
class Deserializer {
262
  reviveProject(project: JSONOutput.ProjectReflection, name?: string): ProjectReflection;
263
  revive<T>(obj: any, root: T): T;
264
}
265

266
namespace JSONOutput {
267
  interface ProjectReflection extends Reflection {
268
    packageVersion?: string;
269
    readme?: string;
270
    changelog?: string;
271
    children?: DeclarationReflection[];
272
    groups?: ReflectionGroup[];
273
    categories?: ReflectionCategory[];
274
  }
275
}
276
```
277

278
[JSON Serialization](./serialization.md)
279

280
### Internationalization
281

282
Multi-language support system for localizing TypeDoc's output interface and messages.
283

284
```typescript { .api }
285
class Internationalization {
286
  setLocale(locale: string): void;
287
  resetLocale(): void;
288
  addTranslations(locale: string, translations: Partial<TranslatableStrings>): void;
289
  proxy(): TranslationProxy;
290
}
291

292
function i18n(key: TranslatedString, ...args: any[]): string;
293

294
interface TranslatableStrings {
295
  theme_implements: string;
296
  theme_indexable: string;
297
  theme_type_declaration: string;
298
  theme_constructor: string;
299
  theme_property: string;
300
  theme_method: string;
301
  theme_call_signature: string;
302
  // ... many more translation keys
303
}
304
```
305

306
[Internationalization](./internationalization.md)
307

308
## Core Types
309

310
### Application Events
311

312
```typescript { .api }
313
interface ApplicationEvents {
314
  BOOTSTRAP_END: [Application];
315
  REVIVE: [ProjectReflection, JSONOutput.ProjectReflection];
316
}
317
```
318

319
### Reflection Enums
320

321
```typescript { .api }
322
enum ReflectionKind {
323
  Project = 0x1,
324
  Module = 0x2,
325
  Namespace = 0x4,
326
  Enum = 0x8,
327
  EnumMember = 0x10,
328
  Variable = 0x20,
329
  Function = 0x40,
330
  Class = 0x80,
331
  Interface = 0x100,
332
  Constructor = 0x200,
333
  Property = 0x400,
334
  Method = 0x800,
335
  CallSignature = 0x1000,
336
  IndexSignature = 0x2000,
337
  ConstructorSignature = 0x4000,
338
  Parameter = 0x8000,
339
  TypeLiteral = 0x10000,
340
  TypeParameter = 0x20000,
341
  Accessor = 0x40000,
342
  GetSignature = 0x80000,
343
  SetSignature = 0x100000,
344
  ObjectLiteral = 0x200000,
345
  TypeAlias = 0x400000,
346
  Reference = 0x800000,
347
  Document = 0x1000000,
348
}
349

350
enum ReflectionFlag {
351
  None = 0,
352
  Private = 1,
353
  Protected = 2,
354
  Public = 4,
355
  Static = 8,
356
  External = 16,
357
  Optional = 32,
358
  Rest = 64,
359
  Abstract = 128,
360
  Const = 256,
361
  Readonly = 512,
362
  Inherited = 1024,
363
}
364
```
365

366
### Configuration Enums
367

368
```typescript { .api }
369
enum ParameterType {
370
  String = "string",
371
  Number = "number",
372
  Boolean = "boolean",
373
  Map = "map",
374
  Mixed = "mixed",
375
  Array = "array",
376
  PathArray = "pathArray",
377
  ModuleArray = "moduleArray",
378
  GlobArray = "globArray",
379
  Object = "object",
380
  Flags = "flags",
381
  Path = "path",
382
  Module = "module",
383
  Glob = "glob",
384
}
385

386
enum CommentStyle {
387
  JSDoc = "jsdoc",
388
  Block = "block", 
389
  Line = "line",
390
  All = "all",
391
}
392

393
enum EntryPointStrategy {
394
  Resolve = "resolve",
395
  Expand = "expand",
396
  Packages = "packages",
397
  Merge = "merge",
398
}
399
```
400

401
### Utility Types
402

403
```typescript { .api }
404
type GlobString = string & { __globBrand: never };
405
type NormalizedPath = string & { __normalizedPathBrand: never };
406
type TranslatedString = string & { __translatedBrand: never };
407

408
interface MinimalSourceFile {
409
  fileName: string;
410
  text: string;
411
}
412

413
interface ComponentPath {
414
  path: string;
415
  last?: boolean;
416
}
417
```