Docma Default Template


Docma includes a built-in template; with a side-bar symbols menu, search and navigation features; and a beautiful layout. Actually you're viewing it right now.

Using this default template is straight-forward. Just set buildConfig.template.path to "default" or omit it.

Template Options

Template specific options that can be used when building your documentation with this default template.

Option Type Default Description
title String "" Title to be set on the top left of the main document and on top of the sidebar. Don't confuse this with document title (tag).
sidebar Boolean true Whether to enable sidebar that lists the documentation symbols; as a menu.
collapsed Boolean false Whether to collapse the sidebar initially by default, on document load.
outline String "flat" Indicates the outline style for the sidebar symbols. If set to "flat" symbols are listed with their long names. If set to "tree", symbols are listed with their short names; indented depending on their hierarchical position.
toolbar Boolean true Specifies whether the toolbar below the sidebar search box should be shown. This toolbar provides buttons for switching between outlines and quick-filtering symbols by symbol-kind.
animations Boolean true Whether animations are enabled for sidebar and listed symbols.
badges Boolean|String true Whether to show symbol badges (that indicate member type and symbol scope) within the sidebar. If set to false, will be used as bullets, instead of badges. Or you can set a string for custom bullets.
symbolMeta Boolean false Which specifies whether to add meta information at the end of each symbol documentation such as code file name and line number.
search Boolean true Whether to enable the search box within the sidebar. For this to be visible, sidebar should be enabled.
navbar Boolean true Whether to enable the navigation bar on top of the main document. This is useful if you have extra views to navigate to; such as a bookmark on the same document, an external guide, demo or a repository page...
navItems Array [] List of navigation items. See Navigation Items below.

Linked labels that build the navigation bar on the top of the document. Each item is an arbitrary Object with the following properties.

Property Type Default Description
label String "" Label of the navigation item. Try keeping this short.
href String "#" Sets the link of the navigation item. Either a bookmark, a relative or external link.
target String undefined Sets the anchor target option. e.g. "_blank" to open the link in new/blank page.
iconClass String undefined One of the built-in icon CSS classes. e.g. "ico-github". You can combine this with classes that define the size of the icon such as "ico-md ico-github". See all icon and size classes in the less file.
items Array undefined Sub-items for this navigation item. You can use label, href and target options. You can also use an additional separator option, which places a horizontal line within the submenu. e.g. { separator: true }.

Usage with Docma

Template options are defined within the build configuration. i.e. buildConfig.template.options.

const buildConfig = {
    template: {
        // Template-specific options
        options: {
            title: "My Library",
            sidebar: true,
            collapsed: false,
            badges: true,
            search: true,
            toolbar: true,
            symbolMeta: true,
            outline: "tree",
            animations: true,
            navbar: true,
            navItems: [
                {
                    label: "Documentation",
                    href: "#",
                    iconClass: "ico-book"
                },
                {
                    label: "Demos",
                    href: "demos.html",
                    iconClass: "ico-mouse-pointer"
                },
                {
                    label: "Download",
                    iconClass: "ico-md ico-download",
                    items: [
                        {
                            label: "v0.5.0-pre",
                            href: "https://github.com/<user>/<repo>/archive/v0.5.0-pre.zip"
                        },
                        {
                            label: "v0.7.0-pre",
                            href: "https://github.com/<user>/<repo>/archive/v0.7.0-pre.zip"
                        },
                        { separator: true },
                        {
                            label: "v1.0.0",
                            href: "https://github.com/<user>/<repo>/archive/v1.0.0.zip"
                        }
                    ]
                },
                {
                    label: "GitHub",
                    href: "https://github.com/<user>/<repo>",
                    target: "_blank",
                    iconClass: "ico-md ico-github"
                }
            ]
        }
    },
    // other build configuration options
    // src, dest, app, jsdoc, markdown, debug, etc...
}

Then you can build your documentation with these customized template options.

Docma.create()
    .build(buildConfig)
    .then(() => {
        console.log('Documentation is built successfully.');
    })
    .catch(err => {
        console.log(err);
    });