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 .
mdoc uses the github "codeblock syntax" to highlight code. E.g.:
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
setting will take precedence and overwrite anything specified in
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
Filename : WhatIsInbaseTitle.
baseTitle: 'mdocs title tag'
Specify the path to the custom templates to use. These should be Handlebar template files
Specify the path to the static asset files (JS/CSS/images, etc)
Change the name of the outputted HTML files using a custom replacement string
return outputNamereplace'.html' '_doc.html';
Change the name displayed on the sidebar and on the index TOC
return fileNamereplace'_doc.html' '';
Pattern that matches files that should be parsed
Pattern that matches files that shouldn't be parsed
Filters file. Return
false to remove files and
true to keep them
Sets which heading should be treated as a section start (and is used for TOC) defaults to
You can also pass custom Handlebars helpers to be used during the compilation.
hbHelpers :var format = require'mout/number/currencyFormat';return formatval;return blockfncontext0;
mdoc -i examples/basic/content -o examples/basic/out
For a list of available commands run:
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.