Dr Mark
Generated summary docs with doctored markdown
Summary docs exemplified by http://redis.io/commands
"Doctored" as in repurposed markdown.
Install
Install the dr
executable globally
sudo npm -g install dr-mark
Install locally for use in a project:
npm install dr-mark --save
Usage
Create a markdown file, structured like so
# ITEM1 TITLE* input1* input2 * etc item1 description --- # ITEM2 TITLE* input1* input2 * etc item2 description
Titles are marked as H1 titles, inputs (e.g. arguments), are listed using bullets, the description stands in it's own paragraph (note the newline spacing). Note the seperator the between item descriptions.
The HTML generated from this markdown does not conform to the usual markdown ruleset. The example will generate the following HTML output.
ITEM1 TITLE input1 input2 etcitem1 description ITEM2 TITLE input1 input2 etcitem2 description
This allows for an optimum styling control of the content, neccessary for creating a column based layout of summary documentation.
Executable
Convert "doctored markdown" to HTML (wrapped in default head and footer html)
dr docs.md > docs.html
Supply header and footer HTML
dr --head header.html --foot footer.html docs.md > docs.html
Output suggested/base docs CSS:
dr --styles
Require
To use dr-mark in a project,
var dr = ;var fs = ;var myMarkdown = fs+''; console
A second argument can be passed to the exported function,
this is called the lexicon
parameter, which defines id's
and class names that appear in the generated HTML (allowing
for completely custom CSS).
The default lexicon is as follows
group: 'api' //id of the <section> wrapping docs field: 'method' //class of each item inputs: 'params' //class of inputs for each item content: 'synopsis' // class of description for each item
Client-side
dr-mark is compatible with browserify
var request = ;var dr = ;
browserify mycode.js > bundle.js
This allows for (for instance) dynamically generating doc pages from Readme.md file on github.
Linking Items
Any inline markdown elements will be faithfully rendered, so to link item titles to pages simply use an inline link. For clarity's sake it's recommended that links are implemented via markdown references.
# [ITEM1 TITLE][]* input1* input2 * etc item1 description [ITEM1 TITLE]: /commands/item1
Credits
Developed by David Mark Clements
Sponsored by nearForm