A Node.js CLI to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as readme.md).
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
tap-snapshots
.editorconfig
.gitignore
.npmrc
.prettierignore
.travis.yml
changelog.md
cli.js
index.js
package.json
readme.md
test-helpers.js

readme.md

jsdoc-md

npm version Build status

A Node.js CLI to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as readme.md).

Setup

To try it out with npx run:

npx jsdoc-md --help

To install jsdoc-md from npm as a dev dependency run:

npm install jsdoc-md --save-dev

Add a script to your package.json:

{
  "scripts": {
    "jsdoc": "jsdoc-md"
  }
}

Then run the script to update docs:

npm run jsdoc

CLI

For detailed CLI usage instructions, run npx jsdoc-md --help.

Option Alias Default Description
--source-glob -s **/*.{mjs,js} JSDoc source file glob pattern.
--markdown-path -m readme.md Path to the markdown file for docs insertion.
--target-heading -t API Markdown file heading to insert docs under.

API

Table of contents

function jsdocMd

Scrapes JSDoc from files to populate a markdown file documentation section.

Parameter Type Description
options Object? Options.
options.sourceGlob string? = **/*.{mjs,js} JSDoc source file glob pattern.
options.markdownPath string? = readme.md Path to the markdown file for docs insertion.
options.targetHeading string? = API Markdown file heading to insert docs under.

Examples

Customizing all options.

const { jsdocMd } = require('jsdoc-md')

jsdocMd({
  sourceGlob: 'index.mjs',
  markdownPath: 'README.md',
  targetHeading: 'Docs'
})

Caveats

No code inference

Missing JSDoc tags are not inferred by inspecting the code, so be sure to use all the necessary tags.

/**
 * The number 1.
 * @kind constant
 * @name ONE
 * @type {number}
 */
const ONE = 1

Tag subset

A JSDoc tag subset is supported:

With the full set of JSDoc tags there is a confusing number of ways to document the same thing. Examples TWO and THREE use unsupported syntax:

/**
 * My namespace.
 * @kind namespace
 * @name MyNamespace
 */
const MyNamespace = {
  /**
   * The number 1.
   * @kind constant
   * @name MyNamespace.ONE
   * @type {number}
   */
  ONE: 1,

  /**
   * The number 2 (unsupported).
   * @constant {number} TWO
   * @memberof MyNamespace
   */
  TWO: 2,

  /**
   * The number 3 (unsupported).
   * @const MyNamespace.THREE
   * @type {number}
   */
  THREE: 3
}

Namepath prefixes

JSDoc namepath prefixes are not supported:

Namepath special characters

JSDoc namepath special characters with surrounding quotes and backslash escapes (e.g. @name a."#b"."\"c") are not supported.

Inline tags

One JSDoc inline tag link syntax is supported for namepath links in JSDoc descriptions and tags with markdown content: [`b` method]{@link A#b}. Use normal markdown syntax for non-namepath links.

Other inline tags such as {@tutorial} are unsupported.

Example content

@example content outside <caption /> (which may also contain markdown) is treated as markdown. This allows multiple code blocks with syntax highlighting and explanatory content such as paragraphs and images. For example:

/**
 * Displays a message in a native popup window.
 * @kind function
 * @name popup
 * @param {string} message Message text.
 * @example <caption>Say `Hello!` to the user.</caption>
 * This usage:
 *
 * ```js
 * popup('Hello!')
 * ```
 *
 * Displays like this on macOS:
 *
 * ![Screenshot](path/to/screenshot.jpg)
 */
const popup = message => alert(message)