API Reference

Reference of meta-doc NodeJS module.

How to create generator object

var MetaDoc = require("../index.js");

try {
    
    var doc = MetaDoc({
        media:    "./my-media",
        pages:    "./my-pages",
        site:     "./my-site",
        template: "./my-template",
        assets:   "./my-template/assets",
        config:   "./my-config.json",
        cache:    "./my-cache.json"
    });

    doc.on("error", function(e){
        //Handler error
        console.error(e.toString());
    });

} catch(e) {
    logger.error(e.toString());
}

MetaDoc(opts)

Constructor accepts configuration object with following properties.

Property name Type Description Default value
media string Path to source media directory. ./media
pages string Path to source pages directory. ./pages
site string Path to documentation output directory. ./site
template string Path to documentation template directory. ./template
assets string Path to documentation template assets directory. ./template/assets
config string Path to global configuration file. ./config.json
cache string Path to compiler cache file. ./cache.json

Registering default shortcodes

//...
doc.useDefaultShortcodes()

useDefaultShortcodes()

Loads module library ./lib/shortcodes.js and registers all default shortcodes.

Registering default helpers

//...
doc.useDefaultHelpers()

useDefaultHelpers()

Loads module library ./lib/helpers.js and registers all default compiler helpers.

Registering custom shortcode

doc.addShortcode("contact", function(opts, content){
    
    if(!opts.first_name || !opts.last_name) return "[Invalid arguments]";
    return '<h2>' + opts.first_name + " " + opts.last_name + '</h2>\n<p class="job-title">' + opts.join(", ") + '</p>\n<p class="about">' + contents + '</p>';

});

Using custom shortcode:

[[contact first_name=John last_name=Doe CEO Founder]]Lorem ipsum...[[/contact]]

Results in:

<h2>John Doe</h2>
<p class="job-title">CEO, Founder</p>
<p class="about">Lorem ipsum...</p>

addShortcode(name, handlerFn)

Method registers new shortcode.

Argument Type Description
name string Shortcode tag name.
handlerFn function Function which is called when processing shortcode. Function returns replacement string.

META Doc is using meta-shortcodes library and uses it's API. Look at it's documentation for more information.

Registering custom helpers

doc.addHelper([ require('markdown-it-attrs') ]);

doc.addHelper([ require('markdown-it-highlightjs') ]);

doc.addHelper([
    require('markdown-it-container'),
    "message"
]);

addHelper(args)

Method registers new compiler helper.

Argument Type Description
args array Array of arguments passed to makrkdown-it module method use.

META Doc is using makrkdown-it module. Look at it's documentation for more information.

You can also browse NPM index for various markdown-it plugins.

Registering custom compiler

var fs = require("fs");

var myCompiler = function(opts, pagesTree, config){

    this.options = opts;
    this.pagesTree = pagesTree;
    this.config = config;
    
};

myCompiler.prototype.compile = function(){

    fs.writeFileSync(this.options.outputDir + "/test.random", Math.random());
    
};

doc.useCompiler(myCompiler);

useCompiler(compiler)

Method registers new compiler.

Argument Type Description
compiler function Constructor of compiler instance.

Compiler instance

Compiler instance must implement follwing methods:

  • #constructor(opts, pagesTree, globalConfig)
  • #compile(changedPages, changedFiles)

For more information look at source code of:

  • ./lib/treeParser.js (pagesTree instance)
  • ./lib/compiler.js (default compiler)
  • ./index.js (compile method)

Cleaning site directory

doc.cleanSite();

cleanSite()

Method recursively deletes all files and directories in documentation <site> (output) directory. Method is used to clean remaining mess and should be called before compilation and copying of any files into output.

Copying media directory

doc.copyMedia();

copyMedia()

Method recursively copies all contents of <media> directory into <site>/media directory.

Copying assets directory

doc.copyAssets();

copyAssets()

Method recursively copies all contents of <assets> directory into <site>/assets directory.

Compiling documentation

doc.compile();

compile()

Method parses documentation tree structure, check for changes aginst cache and executed compilers which compiles changed or new pages to <site> directory.

Watching for changes

doc.watch();

watch()

Method watches for changed in following directories and recompiles documentation when change occurs.

  • <pages>
  • <media>
  • <assets>
  • <template>
  • <config file>

Handle errors

doc.on("error", function(e){
    console.error(e.toString());
});

error

This event is emitted when error occurs.

Error object is passed as event data.

Where to go next?

Usage Writer's Guide