Dr-mark NPM | npm.io

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.

 <section id="api">
    <ul>
        <li><span class="method">ITEM1 TITLE <span class="params">input1 input2  etc</span></span><span class="synopsis">item1 description</span></span>
        </li>
        <li><span class="method">ITEM2 TITLE <span class="params">input1 input2  etc</span></span><span class="synopsis">item2 description</span>
        </li>
    </ul>
</section>

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 = require('dr-mark');
var fs = require('fs');
var myMarkdown = fs.readFileSync('./someMarkdown.md')+'';

console.log(dr(myMarkdown))

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 = require('request');
var dr = require('dr-mark');

request('http://github.com/me/myThing/docs.md', function (err, res, body) {
  console.log(dr(body))
})

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