TypeDoc (typestrong/typedoc)

TypeDoc

https://github.com/typestrong/typedoc
Admin
Documentation generator for TypeScript projects.

Tokens:45,063
Snippets:431
Trust Score:8.8
Update:5 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# TypeDoc

TypeDoc is a documentation generator for TypeScript projects that automatically creates API documentation from TypeScript source code and JSDoc comments. It parses TypeScript files using the TypeScript compiler, extracts type information and documentation comments, then generates comprehensive HTML documentation or JSON output. The tool supports the full TypeScript type system including generics, unions, intersections, and conditional types, making it ideal for library authors and large codebases requiring detailed API documentation.

The architecture separates concerns into three phases: conversion (TypeScript → reflection model), serialization (reflection model → JSON), and rendering (reflection model/JSON → HTML). TypeDoc's plugin system allows extensive customization of the conversion and rendering processes. It supports monorepo/multi-package projects, markdown documentation embedding, internationalization, search functionality with customizable ranking, and theme customization. The tool can be used both as a CLI tool and as a programmatic API for integration into build pipelines.

## APIs and Key Functions

### CLI Usage - Basic Documentation Generation

Generate documentation by pointing TypeDoc at entry point files. TypeDoc automatically discovers tsconfig.json and generates HTML output.

```bash
# Install TypeDoc
npm install typedoc --save-dev

# Generate documentation from a single entry point
typedoc src/index.ts

# Generate from multiple entry points
typedoc src/index.ts src/cli.ts

# Specify output directory (defaults to ./docs)
typedoc src/index.ts --out documentation

# Generate JSON output instead of HTML
typedoc src/index.ts --json docs.json

# Specify TypeScript config file explicitly
typedoc src/index.ts --tsconfig tsconfig.build.json

# Use configuration file
typedoc --options typedoc.json

# Example typedoc.json configuration
cat > typedoc.json << 'EOF'
{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./src/index.ts"],
  "out": "docs",
  "exclude": ["**/*.spec.ts", "**/*.test.ts"],
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "readme": "README.md",
  "name": "My Library Documentation",
  "includeVersion": true,
  "sort": ["source-order"],
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  }
}
EOF

# Generate with custom theme and options
typedoc src/index.ts \
  --theme default \
  --name "My API Documentation" \
  --readme README.md \
  --exclude "**/*.test.ts" \
  --excludePrivate \
  --plugin typedoc-plugin-markdown

# Check version and help
typedoc --version
typedoc --help
```

### Programmatic API - Application Bootstrap and Document Generation

Create documentation programmatically using the Application class. This is the main entry point for integrating TypeDoc into build tools or custom workflows.

```typescript
import { Application, TSConfigReader, TypeDocReader } from "typedoc";

// Bootstrap application with plugins loaded (recommended)
const app = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  tsconfig: "tsconfig.json",
  out: "docs",
  excludePrivate: true,
  excludeProtected: false,
  plugin: ["typedoc-plugin-markdown"]
});

// Convert TypeScript source to project model
const project = await app.convert();

if (project) {
  // Validate the project documentation
  app.validate(project);

  // Generate HTML and JSON outputs based on configuration
  await app.generateOutputs(project);

  console.log("Documentation generated successfully");
}

// Alternative: Bootstrap without plugins (faster, more control)
const simpleApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs",
  pretty: false
});

const simpleProject = await simpleApp.convert();
if (simpleProject) {
  await simpleApp.generateOutputs(simpleProject);
}

// Custom readers for configuration sources
const customApp = await Application.bootstrap(
  { entryPoints: ["src/index.ts"] },
  [new TypeDocReader(), new TSConfigReader()] // Only read from typedoc.json and tsconfig.json
);

// Generate only HTML output to specific directory
const htmlOnlyApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"]
});
const htmlProject = await htmlOnlyApp.convert();
if (htmlProject) {
  await htmlOnlyApp.generateDocs(htmlProject, "./custom-docs");
}

// Generate only JSON output
const jsonOnlyApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"]
});
const jsonProject = await jsonOnlyApp.convert();
if (jsonProject) {
  await jsonOnlyApp.generateJson(jsonProject, "./api.json");
}

// Set custom logger for integration
import { ConsoleLogger, LogLevel } from "typedoc";

const loggedApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"]
});
loggedApp.logger.level = LogLevel.Verbose;

const loggedProject = await loggedApp.convert();
if (loggedProject) {
  await loggedApp.generateOutputs(loggedProject);
}

// Handle errors and validation
const errorApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  treatWarningsAsErrors: true,
  treatValidationWarningsAsErrors: true
});

const errorProject = await errorApp.convert();
if (!errorProject) {
  console.error("Failed to convert project");
  process.exit(1);
}

errorApp.validate(errorProject);
await errorApp.generateOutputs(errorProject);
```

### Monorepo and Multi-Package Documentation

Document multiple packages in a monorepo with separate or merged documentation using the packages entry point strategy.

```bash
# Monorepo structure
# project/
#   packages/
#     package-a/
#       src/
#       package.json
#       tsconfig.json
#       typedoc.json
#     package-b/
#       src/
#       package.json
#       tsconfig.json
#       typedoc.json
#   typedoc.json

# Root typedoc.json for monorepo
cat > typedoc.json << 'EOF'
{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["packages/*"],
  "entryPointStrategy": "packages",
  "out": "docs",
  "name": "My Monorepo Documentation",
  "categorizeByGroup": true,
  "searchCategoryBoosts": {
    "Core": 2,
    "Utilities": 1.5
  }
}
EOF

# Each package's typedoc.json
cat > packages/package-a/typedoc.json << 'EOF'
{
  "displayName": "Package A - Core Library",
  "entryPoints": ["./src/index.ts"],
  "tsconfig": "./tsconfig.json"
}
EOF

# Generate documentation for all packages
typedoc

# Programmatic API for monorepo
import { Application, EntryPointStrategy } from "typedoc";

const monorepoApp = await Application.bootstrapWithPlugins({
  entryPoints: ["packages/*"],
  entryPointStrategy: EntryPointStrategy.Packages,
  out: "docs",
  categorizeByGroup: true
});

const monorepoProject = await monorepoApp.convert();
if (monorepoProject) {
  await monorepoApp.generateOutputs(monorepoProject);
  console.log(`Documented ${monorepoProject.children?.length} packages`);
}

# Merge multiple entry points into single module
cat > typedoc.json << 'EOF'
{
  "entryPoints": ["src/core.ts", "src/utils.ts", "src/api.ts"],
  "entryPointStrategy": "merge",
  "out": "docs"
}
EOF

typedoc

# Programmatic merge strategy
const mergeApp = await Application.bootstrap({
  entryPoints: ["src/core.ts", "src/utils.ts", "src/api.ts"],
  entryPointStrategy: EntryPointStrategy.Merge,
  out: "docs"
});

const mergeProject = await mergeApp.convert();
if (mergeProject) {
  await mergeApp.generateOutputs(mergeProject);
}
```

### JSDoc/TSDoc Comment Documentation

Document code using JSDoc/TSDoc comments with TypeDoc-specific tags for rich documentation generation.

```typescript
/**
 * Calculates the square root of a number with proper error handling.
 *
 * @param x - The number to calculate the root of
 * @returns The square root if x is non-negative, or NaN if x is negative
 *
 * @example
 * ```typescript
 * const result = sqrt(16);
 * console.log(result); // Output: 4
 *
 * const invalid = sqrt(-1);
 * console.log(invalid); // Output: NaN
 * ```
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt | Math.sqrt}
 * @category Math
 */
export function sqrt(x: number): number {
  return Math.sqrt(x);
}

/**
 * Generic function that concatenates two arrays of the same type.
 *
 * @typeParam T - The element type of the arrays
 * @param array1 - First array to concatenate
 * @param array2 - Second array to concatenate
 * @returns A new array containing all elements from both arrays
 *
 * @example
 * ```typescript
 * const numbers = concat([1, 2], [3, 4]);
 * // numbers: [1, 2, 3, 4]
 *
 * const strings = concat(["hello"], ["world"]);
 * // strings: ["hello", "world"]
 * ```
 */
export function concat<T>(array1: T[], array2: T[]): T[] {
  return array1.concat(array2);
}

/**
 * Abstract base class for customer entities.
 *
 * This class provides common functionality for all customer types
 * and demonstrates inheritance hierarchy in documentation.
 *
 * @category Model
 * @abstract
 */
export abstract class Customer {
  /** The customer's unique database identifier. */
  readonly id: number;

  /** The customer's display name. */
  name: string;

  /**
   * Optional contact person name.
   * @internal
   */
  protected contactName?: string;

  /**
   * Creates a new customer instance.
   *
   * @param id - The customer's database ID
   * @param name - The customer's name
   * @param nextOrderNumber - Initial order number (can be string like "#001" or number)
   *
   * @example
   * ```typescript
   * class MyCustomer extends Customer {
   *   constructor(id: number, name: string) {
   *     super(id, name, 1);
   *   }
   * }
   *
   * const customer = new MyCustomer(1, "Acme Corp");
   * ```
   */
  constructor(id: number, name: string, nextOrderNumber: string | number) {
    this.id = id;
    this.name = name;
  }

  /**
   * Called when an order is placed for this customer.
   * Increments the internal order counter.
   *
   * @remarks
   * This method should be called by the order processing system
   * after successful order creation.
   */
  public onOrderPlaced(): void {
    // Implementation
  }
}

/**
 * Interface for HTTP request options.
 *
 * @see {@link makeHttpCall}
 */
export interface HttpOptions {
  /** The URL to request */
  url: string;

  /** HTTP method (e.g., GET, POST, PUT, DELETE) */
  method: string;

  /** HTTP headers (e.g., `{ 'Authorization': 'Bearer token' }`) */
  headers: Record<string, string>;

  /** Request body data */
  body: string | Blob | FormData;

  /** CORS mode for the request */
  mode: "cors" | "no-cors" | "same-origin";
}

/**
 * Makes an HTTP request with the specified options.
 *
 * @param options - Configuration object for the HTTP request
 * @returns Promise resolving to the fetch Response
 *
 * @throws {TypeError} If the URL is invalid
 * @throws {DOMException} If the request is aborted
 *
 * @example
 * ```typescript
 * const response = await makeHttpCall({
 *   url: "https://api.example.com/users",
 *   method: "GET",
 *   headers: { "Authorization": "Bearer token123" },
 *   body: "",
 *   mode: "cors"
 * });
 *
 * const data = await response.json();
 * console.log(data);
 * ```
 */
export function makeHttpCall(options: HttpOptions): Promise<Response> {
  const { url, method, headers, body, mode } = options;
  return fetch(url, { method, headers, body, mode });
}

/**
 * Overloaded function demonstrating multiple signatures.
 *
 * @overload
 * @param a - First number
 * @param b - Second number
 * @returns Concatenated string representation
 */
export function combine(a: number, b: number): string;

/**
 * @overload
 * @param a - First string
 * @param b - Second string
 * @returns Concatenated strings
 */
export function combine(a: string, b: string): string;

export function combine(a: unknown, b: unknown): string {
  return String(a) + String(b);
}

/**
 * @packageDocumentation
 *
 * This is the main package documentation that appears on the index page.
 * Use this to provide an overview of your library.
 *
 * @module MyLibrary
 *
 * @categoryDescription Utilities
 * Helper functions and utility classes for common operations.
 *
 * @categoryDescription Core
 * Core functionality and primary APIs of the library.
 */
```

### JSON Serialization and Deserialization

Export project reflections as JSON for programmatic analysis or import pre-generated documentation.

```typescript
import { Application, JSONOutput, Serializer, Deserializer, ConsoleLogger } from "typedoc";

// Serialize project to JSON
const serializeApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"]
});

const serializeProject = await serializeApp.convert();
if (serializeProject) {
  // Method 1: Use built-in JSON generation
  await serializeApp.generateJson(serializeProject, "./docs.json");

  // Method 2: Use serializer directly for custom processing
  const serializer = new Serializer();
  const jsonOutput: JSONOutput.ProjectReflection = serializer.projectToObject(
    serializeProject,
    process.cwd()
  );

  // Customize or analyze the JSON
  console.log(`Project name: ${jsonOutput.name}`);
  console.log(`Number of children: ${jsonOutput.children?.length ?? 0}`);

  // Save with custom formatting
  const fs = await import("fs/promises");
  await fs.writeFile(
    "./custom-docs.json",
    JSON.stringify(jsonOutput, null, 2)
  );
}

// Deserialize JSON back to ProjectReflection
const deserializeApp = await Application.bootstrap({});
const deserializer = new Deserializer(new ConsoleLogger());

const fs = await import("fs/promises");
const jsonContent = await fs.readFile("./docs.json", "utf-8");
const jsonData: JSONOutput.ProjectReflection = JSON.parse(jsonContent);

const restoredProject = deserializer.reviveProject(
  deserializeApp,
  jsonData
);

// Generate HTML from previously serialized JSON
await deserializeApp.generateDocs(restoredProject, "./docs-from-json");

// Analyze JSON structure programmatically
import type { JSONOutput } from "typedoc";

function analyzeDocumentation(json: JSONOutput.ProjectReflection): void {
  console.log(`Project: ${json.name}`);

  // Count different reflection kinds
  const kindCounts = new Map<string, number>();

  function countKinds(reflection: JSONOutput.DeclarationReflection): void {
    const kind = JSONOutput.ReflectionKind[reflection.kind];
    kindCounts.set(kind, (kindCounts.get(kind) ?? 0) + 1);

    reflection.children?.forEach(countKinds);
  }

  json.children?.forEach(countKinds);

  console.log("\nReflection counts:");
  kindCounts.forEach((count, kind) => {
    console.log(`  ${kind}: ${count}`);
  });
}

const jsonDoc: JSONOutput.ProjectReflection = JSON.parse(
  await fs.readFile("./docs.json", "utf-8")
);
analyzeDocumentation(jsonDoc);

// Merge multiple JSON outputs
async function mergeJsonDocs(
  jsonFiles: string[],
  outputPath: string
): Promise<void> {
  const app = await Application.bootstrap({});
  const deserializer = new Deserializer(app.logger);

  const projects = await Promise.all(
    jsonFiles.map(async (file) => {
      const content = await fs.readFile(file, "utf-8");
      const json: JSONOutput.ProjectReflection = JSON.parse(content);
      return deserializer.reviveProject(app, json);
    })
  );

  // Merge logic would go here
  // Then serialize combined result
  const serializer = new Serializer();
  const merged = serializer.projectToObject(projects[0], process.cwd());

  await fs.writeFile(outputPath, JSON.stringify(merged, null, 2));
}

await mergeJsonDocs(
  ["./package-a-docs.json", "./package-b-docs.json"],
  "./merged-docs.json"
);
```

### Plugin Development and Event System

Extend TypeDoc functionality by creating plugins that hook into the conversion and rendering processes.

```typescript
import {
  Application,
  Converter,
  Renderer,
  Context,
  DeclarationReflection,
  ReflectionKind,
  RendererEvent,
  PageEvent,
  type ApplicationEvents
} from "typedoc";

// Plugin that adds custom processing during conversion
export function load(app: Application): void {
  // Listen to converter events
  app.converter.on(Converter.EVENT_CREATE_DECLARATION, (context: Context, reflection: DeclarationReflection) => {
    // Add custom metadata to all class reflections
    if (reflection.kind === ReflectionKind.Class) {
      reflection.comment?.addTag({
        tagName: "@customTag",
        content: [{ kind: "text", text: "This is a class" }]
      });

      console.log(`Processing class: ${reflection.name}`);
    }
  });

  // Listen to conversion completion
  app.converter.on(Converter.EVENT_RESOLVE_END, (context: Context) => {
    console.log(`Conversion resolved for project: ${context.project.name}`);

    // Post-process all reflections
    for (const reflection of context.project.getReflectionsByKind(ReflectionKind.Function)) {
      console.log(`Function found: ${reflection.name}`);
    }
  });

  // Listen to renderer events
  app.renderer.on(Renderer.EVENT_BEGIN, (event: RendererEvent) => {
    console.log(`Starting to render project: ${event.project.name}`);
  });

  app.renderer.on(PageEvent.BEGIN, (page: PageEvent) => {
    console.log(`Rendering page: ${page.model.name}`);

    // Modify page content
    page.contents = `<!-- Custom header -->\n${page.contents}`;
  });

  // Add custom option
  app.options.addDeclaration({
    name: "customOption",
    help: "A custom plugin option",
    type: ParameterType.String,
    defaultValue: "default"
  });

  console.log(`Plugin loaded with option: ${app.options.getValue("customOption")}`);
}

// Use the plugin
const pluginApp = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  plugin: ["./my-plugin.js"],
  customOption: "custom-value"
});

const project = await pluginApp.convert();
if (project) {
  await pluginApp.generateOutputs(project);
}

// Advanced plugin: Custom theme component
import { DefaultTheme, DefaultThemeRenderContext, JSX, PageEvent } from "typedoc";

class CustomTheme extends DefaultTheme {
  getRenderContext(pageEvent: PageEvent): DefaultThemeRenderContext {
    return new CustomRenderContext(this, pageEvent, this.application.options);
  }
}

class CustomRenderContext extends DefaultThemeRenderContext {
  override header(): JSX.Element {
    return (
      <header>
        <h1>Custom Header</h1>
        {super.header()}
      </header>
    );
  }
}

// Register custom theme in plugin
export function loadThemePlugin(app: Application): void {
  app.renderer.defineTheme("custom", CustomTheme);
}

// Use custom theme
const themedApp = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  plugin: ["./theme-plugin.js"],
  theme: "custom"
});

const themedProject = await themedApp.convert();
if (themedProject) {
  await themedApp.generateOutputs(themedProject);
}
```

### Navigation and Search Configuration

Configure navigation structure, search ranking, and categorization for optimal documentation usability.

```json
{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./src"],
  "out": "docs",

  "navigation": {
    "includeCategories": true,
    "includeGroups": true,
    "includeFolders": false
  },

  "categorizeByGroup": false,
  "defaultCategory": "Other",
  "categoryOrder": ["Core", "Utilities", "Models", "*"],

  "groupOrder": [
    "Classes",
    "Interfaces",
    "Functions",
    "Variables",
    "*"
  ],

  "sort": ["source-order", "required-first", "kind"],

  "searchCategoryBoosts": {
    "Core": 2.0,
    "Utilities": 1.5,
    "Models": 1.2
  },

  "searchGroupBoosts": {
    "Classes": 1.5,
    "Functions": 1.2
  },

  "navigationLinks": {
    "Documentation": "https://docs.example.com",
    "GitHub": "https://github.com/example/repo",
    "NPM": "https://npmjs.com/package/example"
  },

  "sidebarLinks": {
    "API Reference": "https://api.example.com",
    "Changelog": "https://github.com/example/repo/blob/main/CHANGELOG.md"
  },

  "navigationLeaves": [
    "Component",
    "Interface"
  ],

  "visibilityFilters": {
    "protected": false,
    "private": false,
    "inherited": true,
    "external": false
  }
}
```

```typescript
// Programmatic navigation configuration
import { Application } from "typedoc";

const navApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs",

  // Navigation structure
  navigation: {
    includeCategories: true,
    includeGroups: true,
    includeFolders: false
  },

  // Categorization
  categorizeByGroup: false,
  categoryOrder: ["Core", "Utilities", "Models", "*"],

  // Sorting
  sort: ["source-order", "required-first", "kind"],

  // Search boosting
  searchCategoryBoosts: {
    "Core": 2.0,
    "Utilities": 1.5
  },

  searchGroupBoosts: {
    "Classes": 1.5,
    "Functions": 1.2
  },

  // External links
  navigationLinks: {
    "Documentation": "https://docs.example.com",
    "GitHub": "https://github.com/example/repo"
  },

  // Visibility filters
  visibilityFilters: {
    protected: false,
    private: false,
    inherited: true,
    external: false
  }
});

const navProject = await navApp.convert();
if (navProject) {
  await navApp.generateOutputs(navProject);
}
```

### Markdown and External Documentation

Embed markdown documents, code examples, and external documentation files into the generated API docs.

```typescript
/**
 * @packageDocumentation
 *
 * Main package entry point with embedded documentation.
 *
 * @document docs/getting-started.md
 * @document docs/examples.md
 * @document docs/api-guide.md
 */

/**
 * Example function showing code inclusion.
 *
 * @example
 * Basic usage:
 * ```typescript
 * const result = processData({ input: "hello" });
 * console.log(result); // Output: "HELLO"
 * ```
 *
 * @example
 * Advanced usage with error handling:
 * ```typescript
 * try {
 *   const result = processData({ input: "test", validate: true });
 *   if (result) {
 *     console.log("Success:", result);
 *   }
 * } catch (error) {
 *   console.error("Processing failed:", error);
 * }
 * ```
 *
 * @see {@link https://example.com/docs | Full Documentation}
 * @see {@link RelatedFunction} for related functionality
 */
export function processData(options: DataOptions): string {
  return options.input.toUpperCase();
}
```

```bash
# Create markdown documents directory
mkdir -p docs

# Create getting-started.md
cat > docs/getting-started.md << 'EOF'
# Getting Started

This guide will help you get started with the library.

## Installation

```bash
npm install my-library
```

## Quick Start

```typescript
import { processData } from "my-library";

const result = processData({ input: "hello" });
console.log(result);
```

## Configuration

Configure the library using the following options:

- `input`: The data to process
- `validate`: Enable validation (default: false)
- `transform`: Custom transformation function
EOF

# Configure TypeDoc to include markdown
cat > typedoc.json << 'EOF'
{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["./src"],
  "out": "docs",
  "readme": "README.md",
  "includeVersion": true,

  "markdownItOptions": {
    "html": true,
    "linkify": true
  },

  "highlightLanguages": [
    "typescript",
    "javascript",
    "bash",
    "json",
    "yaml",
    "python",
    "rust"
  ]
}
EOF

# Generate documentation with embedded markdown
typedoc

# Programmatic approach
import { Application } from "typedoc";

const docsApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs",
  readme: "README.md",
  includeVersion: true,

  markdownItOptions: {
    html: true,
    linkify: true,
    typographer: true
  },

  highlightLanguages: [
    "typescript",
    "javascript",
    "bash",
    "json"
  ]
});

const docsProject = await docsApp.convert();
if (docsProject) {
  await docsApp.generateOutputs(docsProject);
}
```

### Watch Mode and Incremental Builds

Use watch mode for automatic documentation regeneration during development.

```bash
# Enable watch mode
typedoc --watch

# Watch with specific configuration
typedoc --watch --options typedoc.json

# Programmatic watch mode
import { Application } from "typedoc";

const watchApp = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  out: "docs",
  watch: true,
  preserveWatchOutput: false
});

// The watch mode will automatically handle file changes
// This will run continuously until interrupted
const watchProject = await watchApp.convert();
if (watchProject) {
  await watchApp.generateOutputs(watchProject);
}

// Custom watch implementation with hooks
import { watch } from "fs/promises";

const customWatchApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs"
});

async function rebuildDocs(): Promise<void> {
  console.log("Rebuilding documentation...");
  const project = await customWatchApp.convert();
  if (project) {
    await customWatchApp.generateOutputs(project);
    console.log("Documentation updated");
  }
}

// Watch source directory for changes
const watcher = watch("./src", { recursive: true });

for await (const event of watcher) {
  if (event.filename?.endsWith(".ts")) {
    await rebuildDocs();
  }
}
```

### Validation and Quality Checks

Validate documentation completeness, check for broken links, and enforce documentation standards.

```typescript
import { Application, ValidationOptions } from "typedoc";

// Configure validation options
const validationApp = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs",

  // Validation settings
  validation: {
    notExported: true,        // Warn about referenced but not exported symbols
    notDocumented: true,       // Warn about exports without documentation
    invalidLink: true,         // Warn about broken @link tags
    unusedMergeModuleWith: true // Warn about unused @mergeModuleWith
  },

  // Treat warnings as errors
  treatWarningsAsErrors: false,
  treatValidationWarningsAsErrors: true,

  // Require documentation
  requiredToBeDocumented: [
    "Class",
    "Interface",
    "Property",
    "Method",
    "Function"
  ],

  // Exclude from validation
  excludeNotDocumented: false,
  excludePrivate: true,
  excludeProtected: false,
  excludeInternal: true
});

const validationProject = await validationApp.convert();

if (validationProject) {
  // Explicit validation call
  validationApp.validate(validationProject);

  // Check if there were errors
  if (validationApp.logger.hasErrors()) {
    console.error("Documentation validation failed");
    process.exit(1);
  }

  if (validationApp.logger.hasWarnings()) {
    console.warn("Documentation has warnings");
  }

  await validationApp.generateOutputs(validationProject);
  console.log("Documentation is valid and complete");
}

// Custom validation plugin
export function loadValidationPlugin(app: Application): void {
  app.converter.on("validateProject", (project) => {
    // Custom validation logic
    let errorCount = 0;

    for (const reflection of project.getReflectionsByKind(ReflectionKind.Class)) {
      if (!reflection.comment || !reflection.comment.summary.length) {
        app.logger.error(`Class ${reflection.name} is missing documentation`);
        errorCount++;
      }

      // Check for required tags
      if (reflection.comment && !reflection.comment.getTag("@example")) {
        app.logger.warn(`Class ${reflection.name} is missing @example tag`);
      }
    }

    if (errorCount > 0) {
      app.logger.error(`Found ${errorCount} undocumented classes`);
    }
  });
}

const customValidationApp = await Application.bootstrapWithPlugins({
  entryPoints: ["src/index.ts"],
  plugin: ["./validation-plugin.js"],
  validation: { notDocumented: true }
});

const customProject = await customValidationApp.convert();
if (customProject) {
  customValidationApp.validate(customProject);
  await customValidationApp.generateOutputs(customProject);
}
```

## Summary

TypeDoc provides both command-line and programmatic interfaces for generating TypeScript API documentation. The CLI interface offers quick setup with sensible defaults, while the programmatic API enables deep integration into build systems and custom documentation pipelines. Core use cases include: single-package library documentation, monorepo/multi-package documentation with the packages entry point strategy, embedding markdown guides alongside API references, and exporting documentation as JSON for custom rendering or analysis tools.

The plugin system enables extensive customization through event hooks during conversion (parsing TypeScript) and rendering (generating HTML). Common integration patterns include: using TypeDoc in CI/CD pipelines with validation enabled to enforce documentation standards, generating documentation on pre-commit or pre-push hooks, creating custom themes for branded documentation sites, and combining JSON output with static site generators for unified documentation. TypeDoc's reflection model provides full access to the documented code structure, making it suitable for building documentation analysis tools, custom documentation formats, and automated API compliance checking.