Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/millermedeiros/mdoc

node.js markdown powered documentation generator
https://github.com/millermedeiros/mdoc

Last synced: about 2 months ago
JSON representation

node.js markdown powered documentation generator

Awesome Lists containing this project

README 

        
# 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

](http://blog.millermedeiros.com/2011/03/inline-documentation-why-im-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](http://npmjs.org):



    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'

```



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



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



```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](http://handlebarsjs.com/#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




{{ 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](http://moutjs.com/docs/latest/)

or the [**unofficial** NodeJS api](http://millermedeiros.github.com/mdoc/examples/node_api/doc/)

(uses markdown files from [nodejs repository](https://github.com/joyent/node/tree/master/doc/api) 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.