Usage

How to use META Doc as command line tool or as a JavaScript module.

Installation

To install META Doc globally (recommended):

npm install meta-doc -g

To install META Doc locally:

npm install meta-doc --save

Using as command line tool

Usage: meta-doc [-h] [-v] [--pages-dir PAGES] [--media-dir MEDIA]
                [--site-dir SITE] [--template TEMPLATE] [--assets-dir ASSETS]
                [--config CONFIG] [--cache CACHE] [-i] [-w] [-s] [--port PORT]
                [--verbose {log,debug,info,warn,error}]
                [directory [directory ...]]

Positional arguments:
  directory             Documentation directory

Optional arguments:
  -h, --help            Show this help message and exit.
  -v, --version         Show program's version number and exit.
  --pages-dir PAGES     Pages dir
  --media-dir MEDIA     Media dir
  --site-dir SITE       Site dir
  --template TEMPLATE   Template dir
  --assets-dir ASSETS   Assets dir
  --config CONFIG       Config JSON filename
  --cache CACHE         Cache filename
  -i                    Copy skeleton to selected directory
  -w                    Dynamically watch for changes and recompile
  -s                    Start express server
  --port PORT           Server port
  --verbose {log,debug,info,warn,error}
                        Logging verbose level

Generating documentation once

Following example generates documentation in current directory to site dir.

meta-doc

Creating new documentation

Following example will create new documentation to current directory using default skeleton.

meta-doc -i

Running local server

Following example will start local server and will watch for changes. When something change the documentation will be recompiled.

Server listens by default on port 8080 so it is accessable at http://127.0.0.1:8080/.

meta-doc -s -w

Auto-reload

Special script is injected when running local server. When something has change then page in your browser is automatically reloaded.

Using as NodeJS module

You can also use META Doc as NodeJS module but you have to perform configuration and various actions manually.

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

try {
    
    var doc = MetaDoc();

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

    //Init
    doc.useDefaultShortcodes();
    doc.useDefaultHelpers();
    doc.cleanSite();
    doc.copyMedia();
    doc.copyAssets();
    doc.compile();

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

Compiling

To compile documentation you have to:

  • Require meta-doc module
  • Load default shortcodes
  • Load default helpers
  • Create DOC instance
  • Clean site directory
  • Copy neccesary files
  • Compile documentation

This configuration will use current working directory as documentation root. You can specify each directory path by passing options object to MetaDoc constructor.

Registering shortcodes

doc.addShortcode("upper", function(opts, content){
    return content.toUpperCase();
});

Shortcodes can be registered using addShortcode(name, handler) method.

Default shortcodes can be registered by calling useDefaultShortcodes() method.

Registering helpers

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

Markdown compiler helpers can be registered using addHelper(args) method.

Default helpers can be registered by calling useDefaultHelpers() method.

For available helpers take a look at NPM index.

Watching for changes

doc.watch();

To watch changes and automatically recompile site call watch() method.

Example logger configuration:

logger.toConsole({
    level: args.loglevel,
    timestamp: true,
    colorize: true
});

Logging

META Doc is using meta-logger module for console logging.

Visit meta-logger GitHub page for more information about logging configuration.

Deployment

You can deploy your documentation using various methods:

  1. Upload generated <site> directory to your webserver.
  2. Upload entire documentation and point web server to <site> directory (recommended).
  3. Start meta-doc with -s flag as daemon. Not recommended, local server is for testing purposes.
  4. Use option 1. or 2. and create git hook to automatically deploy changes.

Where to go next?

API Reference Writer's Guide