jsdoc-to-markdown

What is jsdoc-to-markdown?

The jsdoc-to-markdown npm package is a tool that generates markdown documentation from JSDoc comments in your JavaScript code. It is useful for creating comprehensive and readable documentation for your projects.

What are jsdoc-to-markdown's main functionalities?

Generate Markdown Documentation

This feature allows you to generate markdown documentation from JSDoc comments in your JavaScript files. The code sample demonstrates how to use jsdoc-to-markdown to read JSDoc comments from JavaScript files in the 'src' directory and output the generated markdown to 'docs/api.md'.

const jsdoc2md = require('jsdoc-to-markdown');
const fs = require('fs');

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

jsdoc2md.render({ files: inputFiles })
  .then(output => fs.writeFileSync(outputFile, output));

Customizing the Output

This feature allows you to customize the output of the generated markdown documentation using a template. The code sample shows how to use a custom template to format the documentation for a specific module.

const jsdoc2md = require('jsdoc-to-markdown');
const fs = require('fs');

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

const template = `{{#module name="myModule"}}{{>docs}}{{/module}}`;

jsdoc2md.render({ files: inputFiles, template: template })
  .then(output => fs.writeFileSync(outputFile, output));

Filtering Output

This feature allows you to filter the output of the generated markdown documentation. The code sample demonstrates how to disable GitHub Flavored Markdown (GFM) in the output by setting the 'no-gfm' option to true.

const jsdoc2md = require('jsdoc-to-markdown');
const fs = require('fs');

const inputFiles = 'src/**/*.js';
const outputFile = 'docs/api.md';

jsdoc2md.render({ files: inputFiles, 'no-gfm': true })
  .then(output => fs.writeFileSync(outputFile, output));

Other packages similar to jsdoc-to-markdown

documentation

The 'documentation' package is another tool for generating documentation from JSDoc comments. It offers a command-line interface and supports various output formats, including HTML and JSON. Compared to jsdoc-to-markdown, 'documentation' provides more flexibility in terms of output formats but may require more configuration.

jsdoc

The 'jsdoc' package is a popular tool for generating HTML documentation from JSDoc comments. It is highly configurable and supports a wide range of tags and plugins. While 'jsdoc' focuses on generating HTML documentation, jsdoc-to-markdown is specialized in generating markdown documentation, making it more suitable for projects that prefer markdown.

esdoc

The 'esdoc' package is a documentation generator for JavaScript that supports ES6+ syntax. It generates HTML documentation and includes features like coverage reports and test integration. Compared to jsdoc-to-markdown, 'esdoc' is more focused on modern JavaScript syntax and provides additional features like coverage reports.

README

Try the jsdoc2md v2 pre-release

jsdoc-to-markdown

jsdoc documented source code in, markdown format API documentation out.

Synopsis

write documented code:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

run a command:

$ jsdoc2md example/src/protection.js

get markdown docs! (in github-flavored-markdown format by default)

<a name="protection"></a>
## protection(cloak, dagger) ⇒ <code>survival</code>
a quite wonderful function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | privacy gown |
| dagger | <code>object</code> | security     |

this command achieves the same result:

$ jsdoc-parse example/function.js | dmd

Features

• Insert API documention into a README, or any arbitrary document.
• Customisable to a granular level. If the output doesn't suit you, change it.
• Package your modifications, publish to npm and share with others (e.g. dmd-bitbucket)
• Accepts .js or .html input files (parsing html is experimental - more)
• Extends jsdoc with some new tags (more)
• Use any arbitrary tag, e.g. @fulfil, @reject, @hatredlevel etc.

Example output

Some example output creating using jsdoc2md.

Generated README files

These projects insert jsdoc2md output into a readme template.

Project	Notes
handbrake-js	A module exposing two methods and an inner class. The API docs are inserted into this README template by this command: $ jsdoc2md --template jsdoc2md/README.hbs lib/*.js
command-line-args	Demonstrates documentation of ES2015 classes plus the @module, @typicalname, @throws and @alias tags.
array-tools	Very simple module exporting a collection of static methods. Demonstrates use of @category to group identifiers in the member-list.
jesucarr/tokenbucket	Demonstrates --param-list-format list and the documentation of Promises using the @fulfil and @reject tags.
ansi-escape-sequences	Demonstrates usage of @enum {type} (rendered in table format).

Tags

You can see an example of how each jsdoc tag looks when rendered here.

Examples demonstrating various options

To get an idea of the affects the various options have:

• formatting options
  • example-lang
  • module-index-format
  • global-index-format
  • member-index-format
  • param-list-format
  • property-list-format
  • no-gfm
  • separators
  • name format
• parse options
  • html
  • sort-by

Scripting examples

If you can't achieve what you need using the command-line tool you can write a custom script.

• generate one markdown file per class

Templating examples

The default jsdoc2md output might not always suit you. You can supply your using own template using the template option. You can see the template used to generate this README here.

Selectors

• Cherry-pick which documentation appears in the output using selector helpers.
  • {{#module}}
  • {{#class}}

Exemplary APIs

See the wiki for more great API examples. Feel free to add your own!

Install and use

First, document your source code using correct jsdoc syntax then run it through jsdoc-to-markdown using one of the following methods (all tested on Mac OSX, Linux, Windows 8.1 and Windows XP):

Command-line tool

To install the jsdoc2md command-line tool globally, run:

$ npm install -g jsdoc-to-markdown

Some typical use cases:

$ # dump everything you have into a single file
$ jsdoc2md "src/**/*.js" > api.md

$ # split into separate files
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md

$ # embed documentation into a template you made
$ jsdoc2md "src/**/*.js" --template readme.hbs > README.md

Note on globbing

General rule: if your file expression contains ** yet recursion is failing, wrap the expression in quotes (e.g. "lib/**/*.js").

If wrapped in quotes, bash (or your shell) will not attempt file-name expansion on the expression. If you do not use quotes you will require bash version 4+ with globstar enabled for recursion to work.

Add a "generate docs" task to your project workflow

As an npm run task

This is the most lightweight way to add the task - no additional task-running software required. First:

$ npm install jsdoc-to-markdown --save-dev

Then, in the "scripts" section of package.json, add a docs task. For example:

{
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Now, project documentation is generated like so:

$ npm run docs

As a grunt task

See grunt-jsdoc-to-markdown.

As a gulp task

See gulp-jsdoc-to-markdown.

Contributing

Issue reports and patches are encouraged. And the project would benefit from an additional maintainer..

Composition

Essentially, jsdoc2d connects the output of jsdoc-parse to the input of dmd. dmd uses the ddata helper library (also shared by dhtml) and stream-handlebars to generate the output.

API Reference

Example

var jsdoc2md = require("jsdoc-to-markdown")

jsdoc2md([options]) ⇒ TransformStream ⏏

Transforms jsdoc into markdown documentation.

Kind: Exported function
Params

• [options] DmdOptions | ParseOptions - the options

Example
Two ways to use jsdoc2md. Either pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md({ src: "lib/*.js" }).pipe(process.stdout)

or pipe in source code from another source:

> fs.createReadStream("lib/main.js").pipe(jsdoc2md()).pipe(process.stdout)

dmd~DmdOptions

All dmd options and their defaults

Kind: inner class of dmd

• ~DmdOptions
  • .template : string
  • .heading-depth : number
  • .example-lang : string
  • .plugin : array
  • .helper : array
  • .partial : array
  • .name-format : string
  • .no-gfm : boolean
  • .separators : boolean
  • .module-index-format : string
  • .global-index-format : string
  • .param-list-format : string
  • .property-list-format : string
  • .member-index-format : string
  • .group-by : array

dmdOptions.template : string

The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.

Kind: instance property of DmdOptions
Default: "{{>main}}"
Example

var fs = require("fs")
var dmd = require("../")

var template = "The description from my class: {{#class name='MyClass'}}{{description}}{{/class}}"

fs.createReadStream(__dirname + "/my-class.json")
    .pipe(dmd({ template: template }))
    .pipe(process.stdout)

outputs:

The description from my class: MyClass is full of wonder

the equivation operation using the command-line tool:

$ dmd --template template.hbs --src my-class.json

dmdOptions.heading-depth : number

The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading".

Kind: instance property of DmdOptions
Default: 2

dmdOptions.example-lang : string

Specifies the default language used in @example blocks (for syntax-highlighting purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: --example-lang js. Use the special value none for no specific language. While using this option, you can override the supplied language for any @example by specifying the @lang subtag, e.g @example @lang hbs. Specifying @example @lang off will disable code blocks for that example.

Kind: instance property of DmdOptions
Default: "js"

dmdOptions.plugin : array

Use an installed package containing helper and/or partial overrides

Kind: instance property of DmdOptions

dmdOptions.helper : array

handlebars helper files to override or extend the default set

Kind: instance property of DmdOptions

dmdOptions.partial : array

handlebars partial files to override or extend the default set

Kind: instance property of DmdOptions

dmdOptions.name-format : string

Format identifier names in the code style, (i.e. format using backticks or <code></code>)

Kind: instance property of DmdOptions

dmdOptions.no-gfm : boolean

By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.

Kind: instance property of DmdOptions

dmdOptions.separators : boolean

Put <hr> breaks between identifiers. Improves readability on bulky docs.

Kind: instance property of DmdOptions
Default: false

dmdOptions.module-index-format : string

none, grouped, table, dl

Kind: instance property of DmdOptions
Default: "dl"

dmdOptions.global-index-format : string

none, grouped, table, dl

Kind: instance property of DmdOptions
Default: "dl"

dmdOptions.param-list-format : string

Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.

Kind: instance property of DmdOptions
Default: "table"

dmdOptions.property-list-format : string

list, table

Kind: instance property of DmdOptions
Default: "table"

dmdOptions.member-index-format : string

grouped, list

Kind: instance property of DmdOptions
Default: "grouped"

dmdOptions.group-by : array

a list of fields to group member indexes by

Kind: instance property of DmdOptions
Default: ["scope","category"]

jsdocParse~ParseOptions

All options for jsdoc-parse, including defaults

Kind: inner class of jsdocParse

• ~ParseOptions
  • .src : string | Array.<string>
  • .private : boolean
  • .stats : boolean
  • .html : boolean
  • .conf : boolean
  • .sort-by : array

parseOptions.src : string | Array.<string>

A list of javascript source files (or glob expressions) to parse for documentation. If this option is not set jsdoc-parse will wait for source code on stdin (i.e. cat *.js | jsdoc-parse <options>).

Kind: instance property of ParseOptions
Example

var parse = require("jsdoc-parse")
var fs = require("fs")

// either supply one or more file names
parse({ src: "example.js" }).pipe(process.stdout)

// or pipe in source code
fs.createReadStream("example.js").parse().pipe(process.stdout)

parseOptions.private : boolean

Include identifier documentation marked as @private in the output

Kind: instance property of ParseOptions
Default: false

parseOptions.stats : boolean

Print a few stats about the doclets parsed

Kind: instance property of ParseOptions

parseOptions.html : boolean

Enable experimental parsing of .html files.

Kind: instance property of ParseOptions
Default: false

parseOptions.conf : boolean

Path to a jsdoc configuration file, passed directly to jsdoc -c.

Kind: instance property of ParseOptions

parseOptions.sort-by : array

Sort by one of more fields, e.g. --sort-by kind category. Pass the special value none to remove the default sort order.

Kind: instance property of ParseOptions
Default: ["scope","category","kind","order"]

---

© 2014-16 Lloyd Brookes <[e-mail]>. Documented by jsdoc-to-markdown.