@godaddy/dmd

Plugin for jsdoc2md with improved readability and GitHub Flavored Markdown compatibility.

This plugin borrows from dmd-readable and dmd-bitbucket with additional treatments. No HTML tags are generated within the markdown. Headers are simplified with no nested links. Content links to headers are generated with GitHub-style slugs. Reference-style links are used instead of being inline.

See the mock file for an example of a generated document.

Installation

Install it as a devDependency in target project:

$ npm install @godaddy/dmd --save-dev

Usage

Then pass the plugin name to jsdoc2md or dmd to generate docs:

$ jsdoc2md --plugin @godaddy/dmd --files lib/*.js

Formatting

Index Tables

This plugins prefers table for the index format. The description column uses the first paragraph or line break of the items description. This provides a more readable and concise table of contents. The full description will still be used in the body below. When authoring jsdocs, keep this in mind when descriptions get long: you can have a short summary paragraph, followed by detailed paragraphs and examples.

Reference Links

Another help to readability is the use of shortcut reference links. This leaves the link text in the content, with the destination declared out of the way at the bottom of the document. In some cases, collapsed reference links are used to avoid conflicts and to handle links with brackets in the link text.