docma

_{© 2018, Onur Yıldırım (@onury).}

A powerful tool to easily generate beautiful HTML documentation from Javascript (JSDoc), Markdown and HTML files.

Features

• Parse JSDoc documentation, Markdown and HTML files.
• Build a cool SPA (Single Page Application) from parsed files.
• Generate multiple/separate API documentations by grouping JS files.
• Path or Query-string based app routing.
• Non-opinionated engine, built-in template with cool opinions. :sunglasses:
• Supports custom templates, comes with template authoring tools.
• Works great with GitHub Pages, Amazon S3, Nginx, Apache, etc...
• Build via API or CLI.
• Extremely configurable and debuggable.
• Well documented. :point_up:

...like this:

_{This is generated with the built-in template, Zebra.}
click to view live

Installation

npm i docma -g

Building Documentation with CLI

You can use Docma CLI to build documentations directly from your console. Once you create the configuration (JSON) file, it's quite simple.

docma -c path/to/docma.json

You can even serve the docs locally and test.

docma serve path/to/docs

See

• Docma CLI Reference
• Build Configuration

Building Documentation Programmatically

If you need to build documentation from within your code, use the API.

const Docma = require('docma');

Either by passing a configuration object.

const config = {
    src: [
        './code/**/*.js',
        './README.md'
    ],
    dest: './output/doc'
};
Docma.create()
    .build(config)
    .then(success => console.log('Documentation is built successfully.'))
    .catch(error => console.log(error));

Or by reading configuration from a JSON file.

Docma.create()
    .build('./path/to/docma.json')
    .catch(error => console.log(error));

See Docma API Reference.

Parsed Output

To investigate the parsed JSDoc output, enable the debug option that will create a JSON output(s) within the root of the destination directory. If you have a problem with the parsed documentation data, open an issue @ jsdoc-x. (I'm the author.)

For markdown output issues (that are not related with style), you can open an issue @ marked.

Change-log

See CHANGELOG.
Note: If you're upgrading from Docma v1.x to v2.x, there are some breaking changes.

Documentation

Read Docma documentation, built with Docma, for a Docma demo... :eyes:

License

MIT. You don't have to include any copyright notice in your documentation output or templates but I'd appreciate if you let people know about this tool so we can read better documentations.

Emoji shortcuts used in source markdown files are parsed into twemoji. Graphics and icons licensed under CC-BY 4.0.

Related Modules

• jsdoc-x — Parser for outputting a Javascript object from documented code via JSDoc's explain (-X) command.
• marked — A full-featured markdown parser and compiler, written in JavaScript. Built for speed.
• dustjs — Asynchronous Javascript templating for the browser and server.

Changelog

2.0.0 (2018-04-12)

This is a big release with some breaking changes.
Please read this changelog thoroughly before updating your Docma configuration.

Docma (Builder)

Added

• Support for documenting code with ES2015 syntax. (JSDoc and jsdoc-x dep. update.) Fixes #18 and #21.
• assets build configuration which provides ability to copy defined asset files/directories to build directory; so you can use/link to non-source, static asset files (such as images, PDFs, etc). See [build configuration][build-config]. Fixes #29.
• Pre-build and post-build process support for Docma templates. See Docma Templates documentation.
• markdown.xhtml option for build configuration.
• Docma version compatibility check for Docma templates.
• clean option that specifies whether to empty destination directory before the build. Default is false.
• Build statistics logs to console output. Now, displaying gzipped size of generated (docma-web) script, in addition to minified size; and more detailed summary of routes configured.

Fixed

• An issue where the builder would not check for duplicate route names with the same route type (and silently overwrite the generated content file).
• An issue where compiled template scripts were altered when full-debug is enabled.
• An issue with redirecting a page when the routing method is set to "path".
• An issue with images in HTML (generated from markdown) that would overflow out of page. Now, limiting the image width to 100% of parent container while keeping the aspect ratio.
• An issue with generated heading ids when building docs from markdown. Other HTML tags contained within the heading were not ignored, resulting in too complex ids (bookmarks).

Changed

• BREAKING: Due to several upgrades (such as jsdom), Docma v2+ requires Node.js v6 or newer.
• Greatly improved the symbol sorting logic ([jsdoc-x][jsdoc-x]). You can now sort by scope, by access type, by kind, grouped or alphabetic (default). See jsdoc.sort option in [build configuration][build-config].
• The destination directory is not auto-cleaned anymore before the build. Use clean option for the old behavior. Fixes #34.
• Improved markdown parser. Both <h1 /> and <h2 /> tags are now followed with a <hr/>, like on GitHub.
• Updated core dependencies to their latest versions.
• Migrated all code to ES2015.
• BREAKING: Docma templates are now node modules. Docma still comes with an updated, built-in default template (Zebra). But templates designed for Docma v1.x will not work with Docma v2.x.

Removed

• For template authors only:
  • BREAKING: docma.template.json file that defines the template build and configuration options is dropped in favor of template module main (JS) file or package.json. There are several other improvements. See updated documentation on Creating Docma Templates.
  • BREAKING: compile property of template configuration is removed. Now, scripts or less/sass files of the template should be pre-compiled. This is logical and speeds up the documentation build process of Docma.

Docma CLI

Added

• Option --clean to empty destination directory before the build.
• Command docma serve for starting a static server for serving / testing the generated SPA.
• Command docma template init for initializing a new Docma template project.
• Command docma template doctor for diagnosing a Docma template. Useful for template authors.

Changed

• Dropped default configuration file name docma.config.json in favor of docma.json (shorter) and .docma.json if you need to hide it. This does not break anything, you can still use the former if you want.
• CLI will now auto-check for a docma.json (or .docma.json) file in the current working directory if -c option is omitted.
• Options -v (lowercase) and -V (uppercase) are swapped. -v gets the Docma version now (alias --version). And -V is --verbose.

See [CLI documentation][cli] for detailed information on updated CLI.

Docma Web Core

Added

• Event navigate that's triggered either when route is changed or on hash-change.
• Each symbol in docma.apis[name].documentation instances, now has a .$docmaLink property.
• New utility methods to DocmaWeb.Utils: .type(), .getSymbolLink(), .getLevels(), .getParentName(), .getParent(), .isPackagePrivate(), .isEvent(), .isGenerator(), .isCallback(), .isConstant(), .isInterface(), .isExternal() and .isMixin().
• Utility methods .getCodeTags(), .getFormattedTypeList(). Fixes #33.
• Utility method .trimNewLines(). This also has a dust filter $tnl.

Fixed

• Broken bookmark links due to URI encoded characters after hash (#). e.g. when navigated to #MyClass%7EInnerObject instead of #MyClass~InnerObject.
• An issue with DocmaWeb.Utils.getLongName(), occured after JSDoc core upgrade.
• currentRoute parameter of the route event. Passing null instead of empty route object when route does not exist.
• An issue with DocmaWeb.Utils.isClass() utility method where meta.code.type is not set to ClassDeclaration.
• DocmaWeb.Utils.isProperty() utility method. It'll now return false if symbol is a method/function. This also affects the following methods: .isStaticProperty(), .isInstanceProperty().

Changed

• BREAKING: Docma utility methods are moved to DocmaWeb.Utils static namespace (formerly under docma.utils).
• DocmaWeb.Utils.getSymbolByName() signature is changed.
• Updated web-core dependencies.

Docma Template API

Changed

• Docma templates are now node modules. This is the initial Template API. See updated documentation on Creating Docma Templates.