ruyadorno / mdoc

node.js markdown powered documentation generator

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

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.

Contributing

There are lots of things to improve, check the issues page for a list of bugs and feature requests.

I probably won't have free time to work on it till next year, any help is welcome. (it also keeps me more motivated)

License

Released under the MIT license.

Changelog

v0.3.4 (2013/05/22)

• fix documentation names on windows and assets path. (#19)

v0.3.3 (2013/02/26)

• change bin file encoding to unix (#18)
• print proper version number on cli.

v0.3.2 (2012/07/13)

• fix some incopatibilities with windows paths.

v0.3.1 (2012/02/22)

• only uses descriptions if next block after header is a paragraph (#10)
• improve the way code blocks are converted (#11)
• fix page titles (#12)
• rename template files to "*.hbs"

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.