jsdoc-to-markdown

9.1.3 verified Sat Apr 25 auth: no javascript

Generates Markdown API documentation from JSDoc-annotated JavaScript source code. Current stable version is 9.1.3, released January 2025. The library provides a CLI and a programmable API. It was the first tool to generate Markdown from JSDoc and remains the most popular. Active development with multiple releases per year; breaking changes are managed via major version bumps. Requires Node.js >=12.17. Peer dependency on @75lb/nature for theming. Notable breaking changes include removal of sync methods in v9.0.0 and removal of lodash.omit dependency in v9.1.3.

Common errors

error TypeError: jsdoc2md.renderSync is not a function ↓

cause renderSync was removed in v9.0.0. The API is now async-only.

fix

Use async/await: const output = await jsdoc2md.render({ ... })

error Error: options.source or options.files must be defined ↓

cause In v9.0.0+, input source/files are required.

fix

Provide files (array of paths) or source (string of code) to the render method.

error util.isRegExp is not a function ↓

cause Compatibility issue with Node v23 in older versions.

fix

Upgrade to jsdoc-to-markdown v9.0.4 or later.

error Error: The specified jsdoc binary path contains spaces ↓

cause Spaces in jsdoc path cause parsing issues in versions before v9.0.5.

fix

Upgrade to v9.0.5+ or ensure jsdoc path has no spaces.

Warnings

breaking Removed renderSync(), getTemplateDataSync() and getJsdocDataSync() in v9.0.0. API is now async-only. ↓

fix Use async/await or Promises: const output = await jsdoc2md.render({ ... })

breaking Passing either option.files or option.source is now required in v9.0.0; previously you could omit both and it would read from stdin. ↓

fix Always provide files (array) or source (string) input.

breaking Upgraded to jsdoc v4.0.0 in v8.0.0, which requires Node >=12. Minimum Node increased from v10 to v12. ↓

fix Update Node.js to version 12 or higher.

gotcha The render order of files specified in the 'files' array was respected prior to jsdoc-api v9.0.0 but broken by that version; sorted alphabetically instead. Fixed in jsdoc-api v9.3.5. ↓

fix Upgrade to jsdoc-to-markdown v9.1.3 or later.

deprecated lodash.omit dependency was removed in v9.1.3. No longer needed internally. ↓

fix No action needed; if you were relying on lodash.omit, install it explicitly.

gotcha Spaces in jsdoc binary path can cause jsdoc2md to fail. Fixed in v9.0.5. ↓

fix Upgrade to jsdoc-to-markdown v9.0.5 or later.

gotcha util.isRegExp is not a function error on Node v23 (bug in jsdoc-api). Temporary workaround in v9.0.3, permanent fix in v9.0.4. ↓

fix Upgrade to jsdoc-to-markdown v9.0.4 or later.

Install

npm install jsdoc-to-markdown

yarn add jsdoc-to-markdown

pnpm add jsdoc-to-markdown

Imports

jsdoc2md
wrong
```
const jsdoc2md = require('jsdoc-to-markdown')
```
correct
```
import jsdoc2md from 'jsdoc-to-markdown'
```
Default import provides the main API. CJS require works but ESM is recommended for modern Node.

render

wrong

jsdoc2md.render({ files: 'src/*.js' })

correct

import jsdoc2md from 'jsdoc-to-markdown'; const output = await jsdoc2md.render({ files: ['src/*.js'] })

render() is an async method on the default export. files must be an array, not a string.

getTemplateData

import jsdoc2md from 'jsdoc-to-markdown'; const data = await jsdoc2md.getTemplateData({ files: ['src/*.js'] })

Returns raw JSON data before template rendering. Useful for custom templates.

clear

import jsdoc2md from 'jsdoc-to-markdown'; jsdoc2md.clear()

Clears the jsdoc2md cache. Not commonly needed.

Quickstart

Renders markdown from a single JSDoc-annotated file using the async API.

import jsdoc2md from 'jsdoc-to-markdown';

const output = await jsdoc2md.render({
  files: ['example.js'],
  'heading-depth': 2,
});

console.log(output);

/* example.js:
/**
 * A quite wonderful function.
 * @param {object} - Privacy gown
 * @param {object} - Security
 * @returns {survival}
 */
function protection (cloak, dagger) {}
*/