Creating Docma Templates


Docma parses JSDoc comments into a Javascript object and builds a SPA (Single Page Application) from the given template. The documentation data is then passed to this styled template within a global docma object. Markdown files are converted to HTML files and created in the same destination directory.

Docma templates are essentially web files that mainly make use of Dust.js internally. You can check out the default template for how a template is structured and how partials are used.

Template Structure

/template                        Required
    ├─ docma.template.json          ✔︎      Template configuration.
    ├─ index.html                   ✔︎      Main entry point. (defined in docma.template.json)
    ├─ /partials                    ✔︎      Partials to be compiled.
    │      └─ docma-api.html        ✔︎      Partial for displaying API documentation data.
    │      └─ docma-content.html           Partial for converted markdown and other HTML.
    │      └─ docma-404.html               Partial for 404 - Not Found errors.
    ├─ /js
    ├─ /css
    ├─ /less
    ├─ ...
    :

Template Configuration

Docma templates should have a docma.template.json in the root of the template. This file defines template specific settings such as name of the template, version, the main entry point, document settings, ignored files, etc... This object can be accessed via docma.template.options within the template.

Config Type Default Description
name String Required. Name of the template.
version String "1.0.0" Version of the template. (semver).
author String Required. Author information.
license String Required. Name of the license. e.g. "MIT"
main String "index.html" Name of the main HTML file which is the entry point of the template.
ignore Array undefined List of files or directories to be ignored. Globs allowed.
compile Object undefined Hash-map for files to be compiled. Each key should be a relative path to template directory and each value should be a relative path to output directory (including the file name). Currently only Javascript and Less files are supported. e.g. { "js/main.js": "js/main.min.js", "less/app.less": "css/app.css" }.
options Object undefined Template default options. This object will be merged with the template options defined at build-time.

Note that docma.template.json does not include any build configuration. This only configures the template.

HTML

<template>/index.html is the default entry point (main file) of the generated documentation. It should not include any Dust templates, but can of course include other custom HTML.

It should also include a <div id="docma-main"></div> which all the Dust templates will be compiled into. If you don't define this element, it will be created and dynamically appended to the body of the document.

Note that index.html is the default name of the entry point. You can customize this (name) in docma.template.json.

Example main file (index.html):

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
</head>
<body>
    <div id="docma-main"></div>
    <div id="my-footer"></div>
</body>
</html>

An empty body would also be valid but we want the footer to come after docma-main element. So it's explicitly defined.

Also, note that title of the document is not set. Since this is a template, title will be defined at build time and <title> element will be automatically added to the output document. See Build Configuration.

Partials

Put all Dust.js partials in <template>/partials directory.

You can have sub directories within <template>/partials but all HTML files in these directories will be treated as if they were at the same level (under <template>/partials directory). For example, if you have a template at <template>/partials/widgets/menu.html, you should still include it like this: {>"menu"/} not {>"widgets/menu"/} or {>"partials/widgets/menu"/}. That's why all partials should have unique names.

These HTML files under <template>/partials are pre-compiled into Javascript and will be included as Dust JS templates. (Note that this directory will not be copied over to output directory.)

API Documentation Partial

You should include a (documentation) partial and name it docma-api.html. This partial is required and, will be compiled and loaded into your main HTML (i.e. index.html), when navigated. All JSDoc generated documentation data should be displayed within this partial. JSDoc data is accessible via docma.documentation (array). Since docma is global, within a partial you can iterate documentation symbols/items by {#documentation}..{/documentation}.

A simple example for docma-api.html partial:

{>"menu"/}
{#documentation}
    <h4 id="{.|$id}">{longname}</h4>
    <p>{description}</p>
{/documentation}
{>"footer"/}

Content Partial

In order to include other HTML content in the generated output (such as markdown files converted to HTML); you can also create another partial called docma-content.html. This is optional (and will be auto-generated). However, you should always create one for the template, for better layout and style, since the auto-generated partial will have a very basic layout.

Content partial should include a <div id="docma-content"></div> in itself. Docma will load the target content into this element.

This partial will also be compiled and loaded into in your main HTML, when navigated; so all styles and scripts of the main file will still be available.

A simple example for docma-content.html partial:

{>"menu"/}
<div id="docma-content"></div>
{>"footer"/}

Docma-Web Core

When you build the documentation with your template, a docma-web.js will be generated (and linked in your main HTML); which is the core engine for the documentation web app. This will include everything the app needs such as the documentation data, compiled partials, dustjs engine, etc... (Note that the size of this script depends especially on the generated documentation data.)

See Docma Web API.

Custom Scripts

You have full control over the main HTML file so you can include any Javascript files in it. Docma web core will always be prepended before your scripts; so that you can safely access the global docma object.

Initializing the Template (Web App)

In order to make sure you execute some script after Docma is ready:

// run this in any js file in the browser
docma.on('ready', function () {
    // initialize your code here
    // this runs only once
});

The ready event will only be fired once, right after the initial load. To execute some code after each content or page is rendered, you should use the render event instead.

// run this in any js file in the browser
docma.on('render', currentRoute => {
    if (!currentRoute) {
        console.log('Page not found!');
        return;
    }
    if (currentRoute.type === docma.Route.Type.API) {
        // route generated for JSDoc documentation
        console.log('This is an API documentation route.');
    } else {
        // route generated for markdown/HTML content
        console.log('This is a content route.');
    }
});

CSS & Less

You can include any .css files, anywhere in your template. Since you have control over the main HTML file, you can link any stylesheet in it. As a convention, it's recommended that you place all .css files under <template>/css.

You can also include less files in your template. Main less file(s) to be compiled, should be defined in docma.template.json.

Other Files

You can include any custom files anywhere in your template. They will be copied over into the output directory. If you need to include a file in the template but don't want it to be in the generated output; define it in the docma.template.json file, within the ignore setting.

Docma Default Template

Docma includes a built-in default template for your convenience. Read the details on how to build your documentation with default template.