Wondering what’s next for npm?Check out our public roadmap! »

jsdoc-md

9.1.1 • Public • Published

jsdoc-md

npm version CI 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 install from npm 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

The jsdoc-md command scrapes JSDoc from source files nested in the current working directory to populate a markdown file documentation section. Source files are excluded via .gitignore files.

It implements the function jsdocMd and has the following arguments:

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.

npx examples:

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

Example package.json scripts for a project that uses Prettier to format the readme:

{
  "prepare": "npm run prepare:jsdoc && npm run prepare:prettier",
  "prepare:jsdoc": "jsdoc-md",
  "prepare:prettier": "prettier readme.md --write"
}

API

Table of contents

function jsdocMd

Scrapes JSDoc from source files to populate a markdown file documentation section. Source files are excluded via .gitignore files.

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,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.

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.js';

Ways to require.

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

Customizing all options.

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

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

Install

npm i jsdoc-md

DownloadsWeekly Downloads

963

Version

9.1.1

License

MIT

Unpacked Size

102 kB

Total Files

30

Last publish

Collaborators

  • avatar