Overview
TypeDoc is a documentation generator specifically designed for TypeScript and JavaScript projects. It reads TypeScript source files, extracts type information from the compiler, and combines it with JSDoc-style comments to produce comprehensive API documentation. Output formats include static HTML sites and JSON data that can be consumed by other tools.
TypeDoc understands the full TypeScript type system including generics, union types, interfaces, enums, and decorators. It supports plugins for custom output formats, themes for visual customization, and can document both library APIs and application code.
Installation
# Install as a dev dependency
npm install --save-dev typedoc
# Install globally
npm install -g typedoc
# Install with plugin support
npm install --save-dev typedoc typedoc-plugin-markdown
# Verify installation
npx typedoc --version
Quick Start
# Generate docs from a single entry point
npx typedoc src/index.ts
# Specify output directory
npx typedoc --out docs src/index.ts
# Generate JSON output
npx typedoc --json docs/api.json src/index.ts
# Watch mode for development
npx typedoc --watch
Configuration
typedoc.json
{
"$schema": "https://typedoc.org/schema.json",
"entryPoints": ["src/index.ts"],
"out": "docs",
"name": "My Library API",
"readme": "README.md",
"includeVersion": true,
"excludePrivate": true,
"excludeProtected": false,
"excludeInternal": true,
"excludeExternals": true,
"theme": "default",
"categorizeByGroup": true,
"categoryOrder": ["Core", "Utilities", "Types", "*"],
"navigation": {
"includeCategories": true,
"includeGroups": true
},
"plugin": ["typedoc-plugin-markdown"],
"sort": ["source-order"],
"hideGenerator": true,
"searchInComments": true
}
CLI Options
| Option | Description |
|---|
--entryPoints <files> | Entry point source files |
--out <dir> | Output directory |
--json <file> | Output JSON instead of HTML |
--tsconfig <file> | Path to tsconfig.json |
--readme <file> | README file to include |
--name <name> | Project name in docs |
--theme <name> | Documentation theme |
--exclude <patterns> | Glob patterns to exclude |
--excludePrivate | Exclude private members |
--excludeProtected | Exclude protected members |
--excludeInternal | Exclude @internal tagged items |
--plugin <plugins> | Load plugins |
--watch | Watch for file changes |
--emit doc | Only emit documentation |
--sort <strategy> | Sort order for members |
/**
* Calculates the distance between two points in 2D space.
*
* @remarks
* Uses the Euclidean distance formula.
*
* @example
* ```ts
* const d = distance({ x: 0, y: 0 }, { x: 3, y: 4 });
* console.log(d); // 5
* ```
*
* @param a - The first point
* @param b - The second point
* @returns The Euclidean distance between points a and b
* @throws {@link InvalidPointError} if coordinates are NaN
* @since 1.2.0
* @category Geometry
* @public
*/
export function distance(a: Point, b: Point): number {
return Math.sqrt((b.x - a.x) ** 2 + (b.y - a.y) ** 2);
}
| Tag | Description |
|---|
@param name | Describe a parameter |
@returns | Describe return value |
@throws | Document thrown errors |
@example | Code example |
@remarks | Extended description |
@see | Cross-reference link |
@deprecated | Mark as deprecated with reason |
@since | Version introduced |
@category | Group into category |
@group | Group into custom group |
@public | Mark as public API |
@internal | Mark as internal (excludable) |
@alpha | Alpha release stability |
@beta | Beta release stability |
@typeParam T | Describe a type parameter |
@defaultValue | Document default value |
@link | Inline link to another symbol |
@inheritDoc | Inherit documentation from parent |
Documenting Types
/**
* Configuration options for the HTTP client.
* @category Configuration
*/
export interface ClientConfig {
/** Base URL for all API requests */
baseUrl: string;
/** Request timeout in milliseconds @defaultValue 30000 */
timeout?: number;
/** Custom headers to include with every request */
headers?: Record<string, string>;
}
/**
* Available log levels ordered by severity.
* @category Logging
*/
export enum LogLevel {
/** Detailed debug information */
DEBUG = 'debug',
/** General informational messages */
INFO = 'info',
/** Warning conditions */
WARN = 'warn',
/** Error conditions */
ERROR = 'error',
}
Advanced Usage
Multiple Entry Points
{
"entryPoints": [
"src/core/index.ts",
"src/utils/index.ts",
"src/types/index.ts"
],
"entryPointStrategy": "expand"
}
Monorepo Support
{
"entryPoints": ["packages/*"],
"entryPointStrategy": "packages"
}
Popular Plugins
| Plugin | Description |
|---|
typedoc-plugin-markdown | Output as Markdown files |
typedoc-plugin-mdn-links | Link web APIs to MDN docs |
typedoc-plugin-rename-defaults | Better names for default exports |
typedoc-plugin-merge-modules | Merge multiple modules into one |
typedoc-plugin-missing-exports | Document non-exported types |
Troubleshooting
| Issue | Solution |
|---|
| Types not resolved | Ensure tsconfig.json includes all source files |
| Missing documentation | Add TSDoc comments; check exclude patterns |
| Broken cross-references | Use {@link SymbolName} with correct fully-qualified name |
| Private members appearing | Set excludePrivate: true in config |
| Slow generation | Use --emit doc to skip type checking |
| Plugin not loading | Verify plugin is installed and listed in plugin array |
| Output validation errors | Run with --validation to see specific issues |
| Monorepo packages not found | Use entryPointStrategy: "packages" with correct glob |
