TypeDoc Markdown Plugin

Common errors

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

  cause 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

  cause 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.

  cause 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.

  cause 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.

Warnings

• gotcha Peer 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.
• gotcha Configuration 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.
• gotcha Markdown 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.
• gotcha Advanced 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.

Install

• npm install typedoc-plugin-markdown npm
• yarn add typedoc-plugin-markdown yarn
• pnpm add typedoc-plugin-markdown pnpm

Imports

• plugins
  wrong:

  import 'typedoc-plugin-markdown';

  correct:

  { "plugins": ["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
  wrong:

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

  correct:

  import { MarkdownApplication } 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.

Quickstart

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