[](https://www.npmjs.org/package/dmd)
[](https://www.npmjs.org/package/dmd)
[](https://travis-ci.org/jsdoc2md/dmd)
[](https://david-dm.org/jsdoc2md/dmd)
[](https://github.com/feross/standard)
[](https://gitter.im/jsdoc2md/jsdoc2md?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
# dmd
dmd (document with markdown) is a module containing [handlebars](http://handlebarsjs.com) partials and helpers intended to transform [jsdoc-parse](https://github.com/jsdoc2md/jsdoc-parse) output into markdown API documentation. It exposes [dmd](#module_dmd), a function which requires data and a template. See [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown) for example output.
## Synopsis
With this input file containing [jsdoc-parse](http://handlebarsjs.com) output:
```json
[
{
"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:
```
## fatUse
I am a global variable
**Kind**: global variable
```
## Install and use
### As a library
Install:
```sh
$ npm install dmd --save
```
Example:
```js
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:
```sh
$ npm install -g dmd
```
Example:
```sh
$ cat examples/doclet.json | dmd
$ dmd --help
```
## Templates
The default template contains a single call to the [main](https://github.com/jsdoc2md/dmd/blob/master/partials/main.hbs) partial:
```hbs
{{>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:
```hbs
# 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:
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](https://github.com/jsdoc2md/dmd/blob/master/partials/main.hbs) 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:
```js
exports.generatedDate = function(){
return new Date().toUTCString();
}
```
[Read more about helpers in the handlebars documentation](http://handlebarsjs.com).
### Write a new [main](https://github.com/jsdoc2md/dmd/blob/master/partials/main.hbs) partial
Create a duplicate of the [main](https://github.com/jsdoc2md/dmd/blob/master/partials/main.hbs) partial (typically in the project you are documenting) containing your new footer:
```hbs
{{>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](https://github.com/jsdoc2md/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](https://github.com/jsdoc2md/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](http://nodejs.org/api/stream.html#stream_class_stream_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](#module_dmd--dmd..DmdOptions) - The render options
#### dmd~DmdOptions
All dmd options and their defaults
**Kind**: inner class of [dmd](#exp_module_dmd--dmd)
* [~DmdOptions](#module_dmd--dmd..DmdOptions)
* [.template](#module_dmd--dmd..DmdOptions+template) : string
* [.heading-depth](#module_dmd--dmd..DmdOptions+heading-depth) : number
* [.example-lang](#module_dmd--dmd..DmdOptions+example-lang) : string
* [.plugin](#module_dmd--dmd..DmdOptions+plugin) : array
* [.helper](#module_dmd--dmd..DmdOptions+helper) : array
* [.partial](#module_dmd--dmd..DmdOptions+partial) : array
* [.name-format](#module_dmd--dmd..DmdOptions+name-format) : string
* [.no-gfm](#module_dmd--dmd..DmdOptions+no-gfm) : boolean
* [.separators](#module_dmd--dmd..DmdOptions+separators) : boolean
* [.module-index-format](#module_dmd--dmd..DmdOptions+module-index-format) : string
* [.global-index-format](#module_dmd--dmd..DmdOptions+global-index-format) : string
* [.param-list-format](#module_dmd--dmd..DmdOptions+param-list-format) : string
* [.property-list-format](#module_dmd--dmd..DmdOptions+property-list-format) : string
* [.member-index-format](#module_dmd--dmd..DmdOptions+member-index-format) : string
* [.group-by](#module_dmd--dmd..DmdOptions+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](#module_dmd--dmd..DmdOptions)
**Default**: "{{>main}}"
**Example**
```js
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](#module_dmd--dmd..DmdOptions)
**Default**: 2
##### dmdOptions.example-lang : string
Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#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](#module_dmd--dmd..DmdOptions)
**Default**: "js"
##### dmdOptions.plugin : array
Use an installed package containing helper and/or partial overrides
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
##### dmdOptions.helper : array
handlebars helper files to override or extend the default set
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
##### dmdOptions.partial : array
handlebars partial files to override or extend the default set
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
##### dmdOptions.name-format : string
Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or `[DmdOptions](#module_dmd--dmd..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](#module_dmd--dmd..DmdOptions)
##### dmdOptions.separators : boolean
Put `
` breaks between identifiers. Improves readability on bulky docs.
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
**Default**: false
##### dmdOptions.module-index-format : string
none, grouped, table, dl
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
**Default**: "dl"
##### dmdOptions.global-index-format : string
none, grouped, table, dl
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..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](#module_dmd--dmd..DmdOptions)
**Default**: "table"
##### dmdOptions.property-list-format : string
list, table
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
**Default**: "table"
##### dmdOptions.member-index-format : string
grouped, list
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
**Default**: "grouped"
##### dmdOptions.group-by : array
a list of fields to group member indexes by
**Kind**: instance property of [DmdOptions](#module_dmd--dmd..DmdOptions)
**Default**: ["scope","category"]
* * *
© 2015 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).