jsdoc-md-standard

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-standard --help

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

npm install jsdoc-md-standard --save-dev

Add a script to your package.json:

{
  "scripts": {
    "build:docs": "jsdoc-md-standard"
  }
}

Then run the script to update docs:

npm run build:docs

CLI

For detailed CLI usage instructions, run npx jsdoc-md-standard --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. | | --gitignore | -g | false | Limit the file matching based on the project .gitignore file | | --target-heading | -t | API | Markdown file heading to insert docs under. |

API

Table of contents

• function jsdocMd
  • Examples

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.gitignore | string? = false | Limit the file matching based on the project .gitignore file | | 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:

• @kind
• @name
• @type
• @prop
• @param
• @returns
• @see
• @example
• @ignore

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:

• module:
• external:
• event:

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

This is where jsdoc-md-standard deviates from the upstream jsdoc-md package. That package went in a non-standard direction in how @example tags are treated, which you no doubt found out if you tried to generate documentation via JSDoc via its default template or one of the 100+ community templates.

If you need to generate multiple examples, you add multiple @example tags, plain and simple. That's how we've been writing JSDoc annotations for years and it doesn't make sense to force you to refactor your code comments to turn @example tags into mini blog posts.

Stuffing markdown or paragraphs of text into an @example block sounds like a nice enough idea but breaks every template's attempt to syntax highlight your example code. It also prevents you from using some of the JSDoc plugins that are meant to run doctests off of the raw JavaScript it parses from your examples.

As is standard with JSDoc you can still set captions, wrapped inside of a <caption /> tag [1].