mdoc

mdoc - a simple markdown based documentation generator

This is a simple markdown based documentation generator, it will search all the markdown files inside the "input" directory and output an HTML file for each document, it will also generate a "TOC" (table of contents) for each file and links to all the pages on the index page, it also provides a basic search feature and quick browsing between classes/methods/properties.

Reasoning behind it: inline documentation, why I'm ditching it .

Markdown syntax

mdoc uses the github "codeblock syntax" to highlight code. E.g.:

```js
  //code will be highlighted as JavaScript
```

```python
  //code will be highlighted as Python
```

Currently the parser considers H2 as sections/methods/properties names and will add them to the TOC at the top of each file and automatically generate deep-links to them. It's important to notice that mdoc only recognizes headers on the atx-style as a new section.

The first paragraph after the H2 will be used as description on the sidebar. Currently the search feature only searches copy from the title and description.

For a markdown syntax reference check: http://daringfireball.net/projects/markdown/dingus And also check the structure of the example files.

Install

You can install it through NPM:

npm install -g mdoc

Basic Usage

In a nodeJS file, create the basic outline with the desired configuration options listed below

require('mdoc').run({
    // configuration options (specified below)
    inputDir: 'docs',
    outputDir: 'dist'
});

Run the file node build.js. The outputDir will contain the finished HTML site.

Configuration

Source/Destination Directories (Required)

The following two options contain the source directory to read the documentation from and the destination directory to write the finished product to.

inputDir: 'docs'
outputDir: 'dist'

Basic settings (Optional)

Index File

These two options both specify what should go in to the index file. The indexContent setting will take precedence and overwrite anything specified in indexContentPath.

indexContentPath: 'path/to/index.md'
indexContent: '<h1>Custom markup to be inserted</h1>'

Site Title Tag

This controls what goes in the <title></title> tag in the outputted HTML. The format is Filename : WhatIsInbaseTitle.

baseTitle: 'mdocs title tag'

Advanced settings (Optional)

Custom Templates

Specify the path to the custom templates to use. These should be Handlebar template files

templatePath: 'path/to/template'

Static Assets

Specify the path to the static asset files (JS/CSS/images, etc)

assetsPath: 'path/to/assets'

Outputted File Names

Change the name of the outputted HTML files using a custom replacement string

mapOutName: function (outputName) {
 return outputName.replace('.html', '_doc.html');
}

Display Name

Change the name displayed on the sidebar and on the index TOC

mapTocName: function (fileName, tocObject, title) {
 return fileName.replace('_doc.html', '');
}

Include Files

Pattern that matches files that should be parsed

include: '*.mdown,*.md,*.markdown'

Exclude Files

Pattern that matches files that shouldn't be parsed

exclude: '.*'

Filter Files

Filters file. Return false to remove files and true to keep them

filterFiles: function (fileInfo) {
  return (/math/).test(fileInfo.input);
}

Heading Level

Sets which heading should be treated as a section start (and is used for TOC) defaults to 2

headingLevel: 3

Handlebars Helpers

You can also pass custom Handlebars helpers to be used during the compilation.

hbHelpers : {
  currency: function(val){
    var format = require('mout/number/currencyFormat');
    return format(val);
  },
  first: function(context, block) {
    return block.fn(context[0]);
  }
}

Handlebars context

You can also extend the context that gets provided to the Handlebars templates.

ctx : {
  version: '1.0.0'
  menu: [
    { name: 'Home', link: '/'},
    { name: 'Documentation', link: '/docs'},
    { name: 'API', link: '/docs/api'}
  ],
  site: {
    page: {
      title: 'API Documentation'
    }
  }
}

Those could be used inside your custom template as follow

<ul>
{{#each ctx.menu}}
  <li><a href="{{link}}">{{name}}</a></li>
{{/each}}
</ul>
 
<h2>{{ ctx.site.page.title }}</h2>

Also you can use Handlebars template in your markdown files:

## {{ ctx.site.page.title }}

Current version: {{ ctx.version }}

Parser override

If you want to use another markdown parser you can override the parsing function:

parsingFunction: function(markdownText): {
    return myParser.markdownToHtml(markdownText);
}

Examples

For a live example check: MOUT documentation or the unofficial NodeJS api (uses markdown files from nodejs repository as source)

Command line interface

mdoc -i examples/basic/content -o examples/basic/out

For a list of available commands run:

mdoc -h

Node module

Check files inside the "examples" folder. Run:

cd examples/basic
node build.js

Check output inside "examples/basic/doc".

Check "examples/advanced" for all the available settings.

License

Released under the MIT license.