jm

jsdoc-md

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

Showing:

Popularity

Downloads/wk

184

GitHub Stars

24

Maintenance

Last Commit

2mos ago

Contributors

1

Package

Dependencies

17

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

jsdoc-md logo

jsdoc-md

npm version CI status

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

Setup

To install with npm, run:

npm install jsdoc-md --save-dev

Then, use either the CLI command jsdoc-md or the JS API function jsdocMd to generate documentation.

CLI

Command jsdoc-md

Analyzes JSDoc from source files nested in the current working directory to populate a markdown file documentation section. Source files are excluded via .gitignore files. If the optional peer dependency prettier is installed, the new markdown file contents is Prettier formatted.

It implements the function jsdocMd.

Arguments

ArgumentAliasDefaultDescription
--source-glob-s**/*.{mjs,cjs,js}JSDoc source file glob pattern.
--markdown-path-mreadme.mdPath to the markdown file for docs insertion.
--target-heading-tAPIMarkdown file heading to insert docs under.
--check-cShould an error be thrown instead of updating the markdown file if the contents would change; useful for checking docs are up to date in CI.

Examples

Using npx.

With defaults:

npx jsdoc-md

With arguments:

npx jsdoc-md --source-glob **/*.{mjs,cjs,js} --markdown-path readme.md --target-heading API

Using package scripts.

package.json scripts for a project that also uses eslint and prettier:

{
  "scripts": {
    "jsdoc": "jsdoc-md",
    "test": "npm run test:eslint && npm run test:prettier && npm run test:jsdoc",
    "test:eslint": "eslint .",
    "test:prettier": "prettier -c .",
    "test:jsdoc": "jsdoc-md -c",
    "prepublishOnly": "npm test"
  }
}

Run the test:prettier script before test:jsdoc in the test script so prettier reports formatting errors instead of jsdoc-md.

Whenever the source JSDoc changes, run the jsdoc script:

npm run jsdoc

API

function jsdocMd

Analyzes JSDoc from source files to populate a markdown file documentation section. Source files are excluded via .gitignore files. If the optional peer dependency prettier is installed, the new markdown file contents is Prettier formatted.

ParameterTypeDescription
optionsobject?Options.
options.cwdstring?A directory path to scope the search for source and .gitignore files, defaulting to process.cwd().
options.sourceGlobstring? = **/*.{mjs,cjs,js}JSDoc source file glob pattern.
options.markdownPathstring? = readme.mdPath to the markdown file for docs insertion.
options.targetHeadingstring? = APIMarkdown file heading to insert docs under.
options.checkboolean? = falseShould an error be thrown instead of updating the markdown file if the contents would change; useful for checking docs are up to date in CI.

Returns: Promise\ — Resolves once the operation is done.

Examples

Ways to import.

import { jsdocMd } from 'jsdoc-md';
import jsdocMd from 'jsdoc-md/public/jsdocMd.mjs';

Customizing options.

jsdocMd({
  cwd: '/path/to/project',
  sourceGlob: 'index.mjs',
  markdownPath: 'README.md',
  targetHeading: 'Docs',
}).then(() => {
  console.log('Done!');
});

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:

Namepath prefixes

Some 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);

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100