Registry / serialization / typedoc-plugin-markdown

typedoc-plugin-markdown

library4.11.0jsnpmunverified

typedoc-plugin-markdown is a TypeDoc plugin that converts TypeScript API documentation into Markdown, making it compatible with static site generators like Docusaurus, VitePress, or GitHub Wikis. The current stable version, 4.11.0, reflects an active development approach with frequent minor and patch releases, ensuring ongoing enhancements and bug fixes. Its core function is to replace TypeDoc's default HTML theme with a built-in Markdown theme, offering extensive configuration options for various Markdown dialects and output structures. This plugin differentiates itself by providing fine-grained control over markdown generation, including custom routers for file organization, support for Prettier formatting, and options for dynamic content like navigation JSON. It is an essential tool for projects requiring documentation in a portable, text-based format.

serialization

npm install typedoc-plugin-markdown

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPEDOC-PLUGIN-MAR

typedoc-plugin-markdown

serializationjavascriptv4.11.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plugins

✓ { "plugins": ["typedoc-plugin-markdown"] }

✗ import 'typedoc-plugin-markdown';

This plugin is loaded by TypeDoc via its configuration file (e.g., `typedoc.json`) or CLI options, not imported as a JavaScript module into application code. The `plugins` array tells TypeDoc which plugins to activate.

MarkdownApplication

✓ import { MarkdownApplication } from 'typedoc-plugin-markdown';

✗ import * as TypedocMarkdown from 'typedoc-plugin-markdown';

While not for direct application use, `MarkdownApplication` is a type-only interface exported for custom local plugins to align TypeDoc's `Application` typings with modifications introduced by this plugin, particularly for programmatic extensions or hooks.

load

✓ export function load(app: Application) { /* ... */ } // In a custom TypeDoc plugin file.

The `load` function is the entry point for TypeDoc plugins. While this function is *exported* by `typedoc-plugin-markdown` internally, end-users would typically implement their own `load` function in a *separate* custom plugin, importing `MarkdownApplication` for type safety if needed. The plugin itself is loaded by TypeDoc via its `plugins` configuration, which calls this `load` function internally.

Installs TypeDoc and the markdown plugin, configures TypeDoc via `typedoc.json` to process a sample TypeScript file, and generates Markdown API documentation into a specified output directory.

npm install typedoc@0.28.x typedoc-plugin-markdown --save-dev // src/index.ts (example TypeScript file) /** * Represents a user profile. * @interface */ export interface UserProfile { /** The unique identifier for the user. */ id: string; /** The user's full name. */ name: string; /** The user's email address. */ email?: string; /** * Greets the user. * @param greeting Custom greeting message. * @returns A personalized greeting string. */ greet(greeting: string): string; } /** * A utility class for user operations. */ export class UserUtilities { /** * Creates a new user profile. * @param id The user ID. * @param name The user name. * @returns A new UserProfile instance. */ static createProfile(id: string, name: string): UserProfile { return { id, name, greet: (greeting: string) => `${greeting}, ${name}!`, }; } } // typedoc.json { "entryPoints": [ "src/index.ts" ], "out": "docs/api", "plugin": [ "typedoc-plugin-markdown" ], "entryDocument": "index.md", "excludePrivate": true, "excludeProtected": true, "hideInPageTOC": true, "outputFileStrategy": "modules" } # Run TypeDoc from your project root npx typedoc

Debug

Known issues

gotchaPeer Dependency Mismatch: This plugin requires a specific range of TypeDoc versions (e.g., `typedoc@0.28.x`). Using an incompatible TypeDoc version can lead to runtime errors, unexpected behavior, or TypeDoc loading multiple instances warnings.

fix

Always install the `typedoc` version specified in the plugin's `peerDependencies` (e.g., `npm install typedoc@0.28.x --save-dev`). If you encounter 'TypeDoc has been loaded multiple times' warnings, consider using `npm install --legacy-peer-deps` or investigating your dependency tree.

affects: >=4.0

gotchaConfiguration Options Placement: Plugin-specific options (e.g., `entryDocument`, `outputFileStrategy`) must be placed at the root level of your `typedoc.json` configuration, not inside `packageOptions`. Options inside `packageOptions` only apply to TypeDoc's conversion phase, whereas plugin options are applied during rendering.

fix

Ensure all `typedoc-plugin-markdown` options are directly defined as top-level properties within your `typedoc.json` file.

affects: >=4.0

gotchaMarkdown Rendering Inconsistencies (Older Versions): Early versions of `v4.x` could generate Markdown that caused `markdownlint` errors, contained invalid link fragments, or incorrectly handled specific TypeScript syntax (e.g., square brackets in index signatures, union type rendering).

fix

Upgrade to `typedoc-plugin-markdown@4.11.0` or newer to benefit from improved Markdown output quality, better handling of complex types, and fixes for link generation issues.

affects: <4.11.0

gotchaAdvanced Customization Requires ESM: When writing local TypeDoc plugins or hooks that interact with `typedoc-plugin-markdown`, these custom plugins must be consumed as ECMAScript Modules (ESM) due to TypeDoc's modern architecture.

fix

Ensure your custom plugin files use `.mjs` extension or configure `package.json` to treat `.js` files as ESM (e.g., `"type": "module"`), and use `import`/`export` syntax.

affects: >=4.0

Errors

Common errors & fixes

Error: Cannot find module 'typedoc-plugin-markdown'

The plugin package is not installed or TypeDoc cannot locate it based on the `plugins` configuration.

fix

Run `npm install typedoc typedoc-plugin-markdown --save-dev` to ensure the package is installed. Verify `typedoc-plugin-markdown` is correctly listed in your `typedoc.json` `plugins` array.

TypeError: app.options.addReader is not a function

This usually indicates an incompatible version of TypeDoc is installed, leading to API mismatches with the plugin.

fix

Check the `peerDependencies` of `typedoc-plugin-markdown` and install the exact `typedoc@0.28.x` version required (e.g., `npm install typedoc@0.28.x --save-dev`).

Generated Markdown contains [object Object] or [Function] instead of expected type or value definitions.

TypeDoc or the plugin is failing to correctly resolve and render complex TypeScript types, especially for union types, intersection types, or function declarations returning functions.

fix

Update to `typedoc-plugin-markdown@4.11.0` or newer, which includes improved rendering for union types and function returns. Ensure your `tsconfig.json` used by TypeDoc correctly includes all relevant source files for complete type resolution.

My markdownlint reports errors (e.g., empty table cells, invalid links) in the generated documentation.

Earlier versions of the plugin might have generated non-standard Markdown syntax or had issues with link fragment generation.

fix

Upgrade to `typedoc-plugin-markdown@4.10.0` or newer, as this version specifically includes fixes for common markdownlint errors related to tables and link fragments.

Upgrade

Version history

4.11.0latest on npm

Audit

Dependencies

typedocrequiredThis is a TypeDoc plugin and requires TypeDoc as its host environment to function. It explicitly lists `typedoc@0.28.x` as a peer dependency, meaning you must install a compatible version separately.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/typedoc2md/typedoc-plugin-markdown ↗

packagehttps://www.npmjs.com/package/typedoc-plugin-markdown ↗

homepagehttps://typedoc-plugin-markdown.org ↗