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.

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

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

Examples

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.

Changelog

v0.3.0 (2011/12/02)

• allow setting heading level that should be used for TOC and deep links.
• improve toc.name RegExp.
• add option to set assetsPath without needing to copy template files.
• add setting for default brush to Syntax highlighter at the top of asset JS file since some code blocks may not contain metadata.
• add nodejs api to examples.

v0.2.1 (2011/11/28)

• fix syntax highlighter.

v0.2.0 (2011/11/27)

• Command line interface.
• Add support for custom templates.
• Generate TOC and deep-links automatically.
• Switched most settings to optional.
• Fix links and paths to assets on nested folders.

v0.1.0 (2011/11/27)

• initial release.

Changelog

v0.3.0 (2011/12/02)

• allow setting heading level that should be used for TOC and deep links.
• improve toc.name RegExp.
• add option to set assetsPath without needing to copy template files.
• add setting for default brush to Syntax highlighter at the top of asset JS file since some code blocks may not contain metadata.
• add nodejs api to examples.