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 .
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.
You can install it through NPM:
npm install -g mdoc
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.
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'
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>'
This controls what goes in the <title></title> tag in the outputted HTML. The format
is Filename : WhatIsInbaseTitle.
baseTitle: 'mdocs title tag'
Specify the path to the custom templates to use. These should be Handlebar template files
templatePath: 'path/to/template'
Specify the path to the static asset files (JS/CSS/images, etc)
assetsPath: 'path/to/assets'
Change the name of the outputted HTML files using a custom replacement string
mapOutName: function (outputName) {
return outputName.replace('.html', '_doc.html');
}Change the name displayed on the sidebar and on the index TOC
mapTocName: function (fileName, tocObject, title) {
return fileName.replace('_doc.html', '');
}Pattern that matches files that should be parsed
include: '*.mdown,*.md,*.markdown'
Pattern that matches files that shouldn't be parsed
exclude: '.*'
Filters file. Return false to remove files and true to keep them
filterFiles: function (fileInfo) {
return (/math/).test(fileInfo.input);
}Sets which heading should be treated as a section start (and is used for TOC) defaults to 2
headingLevel: 3
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]);
}
}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 }}
If you want to use another markdown parser you can override the parsing function:
parsingFunction: function(markdownText): {
return myParser.markdownToHtml(markdownText);
}For a live example check: MOUT documentation or the unofficial NodeJS api (uses markdown files from nodejs repository as source)
mdoc -i examples/basic/content -o examples/basic/out
For a list of available commands run:
mdoc -h
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.
Released under the MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent