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
).
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
jsdoc-md
Command 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
Argument | Alias | Default | Description |
---|---|---|---|
--source-glob |
-s |
**/*.{mjs,cjs,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. |
--check |
-c |
Should 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-mdWith 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 useseslint
andprettier
:{ "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 beforetest:jsdoc
in thetest
script soprettier
reports formatting errors instead ofjsdoc-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.
Parameter | Type | Description |
---|---|---|
options |
object? | Options. |
options.cwd |
string? | A directory path to scope the search for source and .gitignore files, defaulting to process.cwd() . |
options.sourceGlob |
string? = **/*.{mjs,cjs,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. |
options.check |
boolean? = false
|
Should 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<void> — 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:
@desc
/@description
@kind
@name
@typedef
@callback
@type
@prop
/@property
@arg
/@argument
/@param
@return
/@returns
@emits
/@fires
@see
@example
@ignore
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);