{"id":17388,"library":"typedoc-plugin-markdown","title":"TypeDoc Markdown Plugin","description":"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.","status":"active","version":"4.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/typedoc2md/typedoc-plugin-markdown","tags":["javascript","api","documentation","markdown","typedoc","typescript","typedoc-plugin"],"install":[{"cmd":"npm install typedoc-plugin-markdown","lang":"bash","label":"npm"},{"cmd":"yarn add typedoc-plugin-markdown","lang":"bash","label":"yarn"},{"cmd":"pnpm add typedoc-plugin-markdown","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This 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.","package":"typedoc","optional":false}],"imports":[{"note":"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.","wrong":"import 'typedoc-plugin-markdown';","symbol":"plugins","correct":"{ \"plugins\": [\"typedoc-plugin-markdown\"] }"},{"note":"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.","wrong":"import * as TypedocMarkdown from 'typedoc-plugin-markdown';","symbol":"MarkdownApplication","correct":"import { MarkdownApplication } from 'typedoc-plugin-markdown';"},{"note":"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.","symbol":"load","correct":"export function load(app: Application) { /* ... */ } // In a custom TypeDoc plugin file."}],"quickstart":{"code":"npm install typedoc@0.28.x typedoc-plugin-markdown --save-dev\n\n// src/index.ts (example TypeScript file)\n/**\n * Represents a user profile.\n * @interface\n */\nexport interface UserProfile {\n  /** The unique identifier for the user. */\n  id: string;\n  /** The user's full name. */\n  name: string;\n  /** The user's email address. */\n  email?: string;\n  /**\n   * Greets the user.\n   * @param greeting Custom greeting message.\n   * @returns A personalized greeting string.\n   */\n  greet(greeting: string): string;\n}\n\n/**\n * A utility class for user operations.\n */\nexport class UserUtilities {\n  /**\n   * Creates a new user profile.\n   * @param id The user ID.\n   * @param name The user name.\n   * @returns A new UserProfile instance.\n   */\n  static createProfile(id: string, name: string): UserProfile {\n    return {\n      id,\n      name,\n      greet: (greeting: string) => `${greeting}, ${name}!`,\n    };\n  }\n}\n\n// typedoc.json\n{\n  \"entryPoints\": [\n    \"src/index.ts\"\n  ],\n  \"out\": \"docs/api\",\n  \"plugin\": [\n    \"typedoc-plugin-markdown\"\n  ],\n  \"entryDocument\": \"index.md\",\n  \"excludePrivate\": true,\n  \"excludeProtected\": true,\n  \"hideInPageTOC\": true,\n  \"outputFileStrategy\": \"modules\"\n}\n\n# Run TypeDoc from your project root\nnpx typedoc","lang":"typescript","description":"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."},"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0"},{"fix":"Ensure all `typedoc-plugin-markdown` options are directly defined as top-level properties within your `typedoc.json` file.","message":"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.","severity":"gotcha","affected_versions":">=4.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":"<4.11.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The plugin package is not installed or TypeDoc cannot locate it based on the `plugins` configuration.","error":"Error: Cannot find module 'typedoc-plugin-markdown'"},{"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`).","cause":"This usually indicates an incompatible version of TypeDoc is installed, leading to API mismatches with the plugin.","error":"TypeError: app.options.addReader is not a function"},{"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.","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.","error":"Generated Markdown contains [object Object] or [Function] instead of expected type or value definitions."},{"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.","cause":"Earlier versions of the plugin might have generated non-standard Markdown syntax or had issues with link fragment generation.","error":"My markdownlint reports errors (e.g., empty table cells, invalid links) in the generated documentation."}],"ecosystem":"npm","meta_description":null}