jsdoc-to-markdown

This documentation is a work-in-progress

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)
Also documents javascript within html input files (experimental - more)
Extends the jsdoc with some new tags (more)

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`
array-tools	Very simple module exporting a collection of static methods. Demonstrates use of `@typicalname` (set to `a`) and the `@category` tag to group identifiers in the member-list.
ansi-escape-sequences	Demonstrates usage of `@enum {type}` (rendered in table format).
file-set	Simple module exporting a class.

Examples demonstrating various options

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

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 in your documentation

Templating examples

The default jsdoc2md output might not always suit you. You can supply your using own template using the template option.

Selectors

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

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.

Compatible Platforms

All these methods are 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.

$ 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, jsdocm2d 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`

The default language to use when syntax highlighting fenced-code blocks in @example tags.

Kind: instance property of DmdOptions
Default: "js"