dmd

dmd (document with markdown) is a collection of handlebars templates for generating markdown documentation from jsdoc-parse input data. It is the default template set used by jsdoc-to-markdown.

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.

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:

$ npm install dmd --save

Example:

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

Install the dmd tool globally:

$ npm install -g dmd

Example:

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

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

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:

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

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.

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

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] object - The render options
    • [.template] string - A handlebars template to insert your documentation into, the default is "{{>main}}".
    • [.heading-depth] number = 2 - the heading depth to begin the docs from (e.g. 2 starts from a markdown heading of "##").
    • [.example-lang] string - for syntax highlighting on github
    • [.partial] string | Array.<string> - overrides
    • [.helper] string | Array.<string> - overrides
    • [.plugin] string | Array.<string> - packages containing overrides

© 2015 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.