TypeDoc

TypeDoc is a documentation generator built specifically for TypeScript projects. Rather than parsing comments with regular expressions, it drives the TypeScript compiler API directly, so the documentation it produces reflects the project’s actual, fully-resolved types — generics, conditional types, unions, and inferred return types included — not an approximation of them.

Running typedoc against a project’s entry points (auto-detected from package.json and tsconfig.json, or specified explicitly) walks the compiled program and produces a ProjectReflection tree of declarations, which is then rendered to a static HTML site or serialized to JSON for other tools to consume. A packages entry-point strategy lets a monorepo’s individual packages be converted separately and merged into one unified site, which is how TypeDoc documents its own multi-package output today.

The conversion and rendering pipeline is built around a plugin/component architecture: converter plugins (grouping, categorization, @inheritDoc, cross-reference linking) transform the reflection tree, and output plugins (navigation, sitemap, search index, hierarchy) shape the rendered site. Third-party plugins published under the typedoc-plugin-* convention hook into the same event system, and custom themes can replace the default renderer entirely.

TypeDoc also validates what it converts — dedicated modules check for broken @link references, undocumented exports, and invalid file paths, surfacing documentation gaps as build errors rather than silent omissions.

What You Get

• A static HTML documentation site generated from TSDoc-style comments and fully compiler-resolved types
• A packages entry-point strategy that documents a monorepo’s packages individually and merges them into one site
• A plugin architecture (typedoc-plugin-*) that can hook into conversion and rendering to add custom behavior
• Pluggable themes and a router abstraction that separate URL/page structure from rendering logic
• Built-in validation that flags broken @link references, undocumented exports, and invalid file paths as errors
• JSON output mode for feeding the resolved project model into other documentation or tooling pipelines

Common Use Cases

• Publishing public API reference docs for an npm library alongside its README
• Generating a unified documentation site for a multi-package monorepo
• Catching undocumented public exports and broken doc-comment links in CI before a release
• Feeding TypeDoc’s JSON output into a custom documentation site or internal developer portal

Under The Hood

Architecture

TypeDoc’s pipeline runs from bin/typedoc through cli.ts, which bootstraps an Application with a chain of option readers (ArgumentsReader, TypeDocReader, PackageJsonReader, TSConfigReader). The Application hands entry points to the Converter (src/lib/converter), which drives the TypeScript compiler to build a full program and walks its symbols through a sequence of composable plugins (CategoryPlugin, CommentPlugin, GroupPlugin, ImplementsPlugin, InheritDocPlugin, LinkResolverPlugin, PackagePlugin, TypePlugin, and others) to produce a tree of Reflection objects (DeclarationReflection, ContainerReflection, SignatureReflection) rooted at a ProjectReflection. That model can be serialized to JSON (src/lib/serialization) or handed to the Renderer (src/lib/output), which pairs a Theme with a Router and its own output plugins (navigation, sitemap, search index via lunr, hierarchy) to produce the final site. Every stage is built on a shared AbstractComponent/event-dispatcher pattern, so both conversion and rendering are extensible by third-party plugins without touching core code — but that also means the Reflection tree is the load-bearing abstraction that every theme and plugin is written against.

Tech Stack

Written in TypeScript (ESM, "type": "module"") and built with a peer dependency spanning TypeScript 5.0 through 6.0, so it tracks new compiler releases without pinning to one. Runtime dependencies are deliberately narrow: @gerrit0/mini-shiki for syntax highlighting, lunr for the generated search index, markdown-it for rendering doc-comment markdown, minimatch for glob-based option matching, and yaml for config file parsing. The build itself runs through hereby, a custom task runner (Herebyfile.mjs) that wraps esbuild for bundling; the docs site is a separate site/ tree built and published through its own GitHub Actions workflow. Package management is pinned to pnpm 10+.

Code Quality

The test suite spans 481 files across dedicated converter, output, renderer, plugins, models, utils, and module directories, run through mocha with c8 coverage reporting — a conversion pipeline this central to a documentation tool is exercised end to end rather than spot-checked. Linting runs through ESLint with typescript-eslint against an extensive custom rule configuration, formatting is enforced via dprint, and CI workflows cover linting, testing, and the documentation site build on every change. Naming and typing are consistent throughout, as expected from a project whose whole purpose is modeling TypeScript’s own type system.

What Makes It Unique

TypeDoc’s core differentiator is that it never guesses at types — it asks the TypeScript compiler for them, so generics, conditional types, and inferred signatures show up in documentation exactly as the compiler sees them, not as a regex’s best effort. Layered on top of that is a genuine plugin and theming system rather than a handful of config flags, a monorepo-aware entry-point strategy that merges multiple packages into one coherent site, and built-in documentation validation — broken links, undocumented exports, invalid paths — that treats documentation completeness as something CI can enforce, which is unusual among documentation generators.