dmd

dmd (document with markdown) is a module containing handlebars partials and helpers intended to transform jsdoc-parse output into markdown API documentation. It exposes dmd, a function which requires data and a template. See jsdoc-to-markdown for example output.

Synopsis

With this input file containing jsdoc-parse output:

[
    {
        "id": "fatUse",
        "name": "fatUse",
        "kind": "member",
        "description": "I am a global variable",
        "scope": "global"
    }
]

this command:

$ cat examples/input/doclet.json | dmd

produces this markdown output:

<a name="fatUse"></a>
## fatUse
I am a global variable

**Kind**: global variable

Install and use

As a library

Install:

$ npm install dmd --save

Example:

var dmd = require("dmd");

var options = {
   template: "my-template.hbs"
};
process.stdin.pipe(dmd(options)).pipe(process.stdout);

At the command line

Install the dmd tool globally:

$ npm install -g dmd

Example:

$ cat examples/doclet.json | dmd
$ dmd --help

Templates

The default template contains a single call to the main partial:

{{>main}}

This partial outputs all documentation and an index (if there are enough items). You can customise the output by supplying your own template. For example, you could write a template like this:

# A Module
This is the readme for a module. 

## Install
Install it using the power of thought. While body-popping.

# API Documentation
{{>main}}

and employ it like this:

$ cat your-docs.json | dmd --template readme-template.hbs

Customising

You can customise the generated documentation to taste by overriding or adding partials and/or helpers.

For example, let's say you wanted this datestamp at the bottom of your generated docs:

**documentation generated on Sun, 01 Mar 2015 09:30:17 GMT**

You need to do two things:

Write a helper method to return the date in your preferred format
Override the appropriate partial, inserting a mustache tag (e.g. ``) where you would like it to appear. We'll override the main partial.

Write a new helper

A helper file is just a plain commonJS module. Each method exposed on the module will be available as a helper in your templates. So, our new helper module:

exports.generatedDate = function(){
    return new Date().toUTCString();
}

Read more about helpers in the handlebars documentation.

Write a new main partial

Create a duplicate of the main partial (typically in the project you are documenting) containing your new footer:

{{>main-index~}}
{{>all-docs~}}

**documentation generated on {{generatedDate}}**

the file basename of a partial is significant - if you wish to override main (invoked by {{>main}}) then the filename of your partial must be main.hbs.

Employ

To use the overrides, pass their file names as options to dmd (or jsdoc-to-markdown if you're using that):

$ cat your-parsed-docs.json | dmd --partial custom/main.hbs --helper custom/generatedDate.js

If you have multiple overrides, the syntax is

$ cat your-parsed-docs.json | dmd --partial override1.hbs override2.hbs

Globbing also works:

$ cat your-parsed-docs.json | dmd --partial overrides/*.hbs

Create a plugin

If you wish to version-control and/or share your customisations you can create a plugin for distribution via npm. See dmd-plugin-example as an example and boilerplate to get you started.

Once you have your plugin, install it where required as a dev-dependency. Then supply the plugin package name(s) to the --plugin option, for example:

$ cd my-project
$ npm install dmd-plugin-example --save-dev
$ jsdoc2md lib/my-module.js --plugin dmd-plugin-example

API Reference

dmd([options]) ⇒ `Transform` ⏏

Transforms doclet data into markdown documentation. Returns a transform stream - pipe doclet data in to receive rendered markdown out.

Kind: Exported function
Params

[options] DmdOptions - The render options

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"