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.
Install it as a devDependency in target project:
$ npm install @godaddy/dmd --save-dev
Then pass the plugin name to
dmd to generate docs:
$ jsdoc2md --plugin @godaddy/dmd --files lib/*.js
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.
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.