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

`javascript
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'
`

$3

#### 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: '

Custom markup to be inserted

'
`

#### Site Title Tag

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

baseTitle: 'mdocs title tag'

$3

#### 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

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

#### Display Name

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

`javascript
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

`javascript
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.

`js
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.

`js
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

`html

{{#each ctx.menu}}

• {{name}}

{{/each}}

{{ ctx.site.page.title }}

`

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:

`javascript
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)

$3

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

For a list of available commands run:

mdoc -h

$3

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.