docma-template-zebra

This is the default template for Docma; with a side-bar symbols menu, search and navigation features; and a beautiful layout.

click to view live

Usage

1. Make sure you have the latest Docma installed.
2. Although Zebra is installed together with Docma, you can still install/update this template via npm: npm i docma-template-zebra -D
3. Set template.path to "default" or "zebra" or omit it in your build configuration (docma.json).
4. Configure and set template.options as described below.

Template Options

Template specific options that can be used when building your documentation with Zebra.

Option	Type	Description
title	String|Object	Title to be set both on the navbar and sidebar. If you want to set a link for these titles, pass an object. Default: "" Note: Don't confuse this with document title (tag) which is set via app.title in the build configuration.
↳ title.label	String	Title to be set both on navbar and sidebar. Default: ""
↳ title.href	String	Link to be set for both navbar and sidebar titles. Default: "#"
logo	String|Object	URL of your logo to be used both in the sidebar and navbar, on the left of the title. If you need to set separate logos for dark (sidebar) and light (navbar) backgrounds, set this to an object. Recommended size of a logo image is 120 x 120 pixels. Default: null
↳ logo.dark	String	URL for dark logo. Default: null
↳ logo.light	String	URL for light logo. Default: null
sidebar	Object|Boolean	Contains settings for the sidebar that lists the documentation symbols; as an outline menu. To simply toggle this with default settings, pass a boolean. For detailed configuration pass an object. Default: true
↳ sidebar.enabled	Boolean	Whether to the sidebar should be visible/enabled... Default: true
↳ sidebar.collapsed	Boolean	Whether to collapse the sidebar initially by default, on document load. Default: false
↳ sidebar.outline	String	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; as an indented tree, depending on their hierarchical position. Default: "tree"
↳ sidebar.toolbar	Boolean	Whether the toolbar below the sidebar search-box should be shown. This toolbar provides buttons for switching between outlines, quick-filtering symbols by symbol-kind, etc... Default: true
↳ sidebar.itemsFolded	Boolean	Indicates whether to initially fold symbol items with child members, in the sidebar. Default: false
↳ sidebar.itemsOverflow	String	Specifies how to fit overflowing sidebar items. Either set to "crop" (crops the item and reveals on hover), or "shrink" (decreases font-size until it fits). Default: "crop"
↳ sidebar.animations	Boolean	Whether CSS transitions and animations are enabled for sidebar and listed symbols. Default: true
↳ sidebar.badges	Boolean|String	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. Default: true
↳ sidebar.search	Boolean	Whether to enable the search box within the sidebar. For this to be visible, sidebar should be enabled. Default: true
symbols	Object	Contains settings for symbol definition documentation. Default: {}
↳ symbols.autoLink	Boolean|String	Specifies whether documented types should be auto-linked to their sources. Set to "internal" paths (i.e. Docma route if type/object definition is within the generated docs) or "external" (MDN docs if it's a JS or Web-API built-in type/object); or true for both. Default: true
↳ symbols.meta	Boolean	Whether to add meta information at the end of each symbol documentation such as code file name and line number. Default: false
↳ symbols.params	String	Specifies the layout style for documented parameters of a symbol. Possible values are "list" or "table". Default: "list"
↳ symbols.props	String	Specifies the layout style for documented properties of a symbol. Possible values are "list" or "table". Default: "list"
↳ symbols.enums	String	Specifies the layout style for documented properties of an enumeration symbol. Possible values are "list" or "table". Default: "list"
contentView	Object	Contains settings for content view, which is generated from markdown or HTML files.
↳ contentView.bookmarks	Boolean|String	Whether to automatically add bookmark links for headings. In order to customize the list of heading tags, set to a comma separated tag name list. e.g. "h1,h2". Default: false
↳ contentView.faLibs	String|Array	FontAwesome icon libraries to be included with the generated output. Set to "all" to include all libraries. To include an individual library; set to "solid", "regular" or "brands". Or you can set to a combination of libraries. e.g. "solid,brands". Set to null to exclude FontAwesome from the output. Default: "all"
↳ contentView.faVersion	String	FontAwesome icon library version to be used. Default: "5.5.0"
navbar	Object|Boolean	Contains settings for the navigation bar on top of the main document. This is useful if you have extra views to navigate to. To simply toggle this with default settings, pass a boolean. For detailed configuration pass an object. Default: {}
↳ navbar.enabled	Boolean	Whether to the navbar should be visible/enabled... Default: true
↳ navbar.fixed	Boolean	Whether navbar should be fixed to top of the page. Default: true
↳ navbar.dark	Boolean	Whether to enable dark theme on navbar. Default: false Note: If this is enabled, you don't need to set path for a dark logo.
↳ navbar.animations	Boolean	Whether CSS transitions and animations are enabled for navbar and listed symbols. Default: true
↳ navbar.menu	Array	List of navigation menu items that builds the navbar and submenu items. See Navigation Menu below. Default: []

Navigation Menu

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

Property	Type	Description
label	String	Label of the navigation item. Try keeping this short. Default: ""
href	String	Sets the link of the navigation item. Either a bookmark, a relative or external link. Default: "#"
target	String	Sets the anchor target option. e.g. "_blank" to open the link in new/blank page. Default: undefined
iconClass	String	One of FontAwsome (v5) Free icon CSS classes. e.g. "fab fa-github". You can combine this with a class that define the size of the icon such as "fab fa-github fa-w-16". See this on how to use FontAwsome v5 icons for details. Default: undefined
chevron	Boolean	Toggles the visibility of the dropdown arrow for the corresponding item. Default: true
items	Array	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 }. Default: undefined

Usage with Docma

Template options are defined within the build configuration. i.e. in a docma.json file.

{
    "template": {
        // Docma Template to be used. 
        // Either a path, module name or "default"
        "path": "zebra",
        // Zebra template-specific options
        "options": {
            "title": {
                "label": "My Library",
                "href": "/base/"
            },
            "logo": {
                "dark": "img/dark-logo.png",
                "light": "img/light-logo.png"
            },
            "sidebar": {
                "enabled": true,
                "outline": "tree",
                "collapsed": false,
                "toolbar": true,
                "itemsFolded": false,
                "itemsOverflow": "crop",
                "badges": true,
                "search": true,
                "animations": true
            },
            "symbols": {
                "autoLink": true,
                "params": "list",
                "enums": "list",
                "props": "list",
                "meta": false
            },
            "contentView": {
                "bookmarks": "h1,h2,h3",
                "faLibs": "solid,regular,brands"
            },
            "navbar": {
                "enabled": true,
                "dark": false,
                "animations": true,
                "menu": [
                    {
                        "label": "Docs",
                        "iconClass": "fas fa-book",
                        "href": "./"
                    },
                    {
                        "label": "Demos",
                        "iconClass": "fas fa-mouse-pointer",
                        "href": "?content=demos"
                    },
                    {
                        "label": "Download",
                        "iconClass": "fas fa-cloud-download-alt",
                        "items": [
                            {
                                "label": "v0.5.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",
                        "iconClass": "fab fa-github",
                        "href": "https://github.com/user/repo",
                        "target": "_blank"
                    }
                ]
            }
        }
    },
    // 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('path/to/docma.json')
    .then(() => {
        console.log('Documentation is built successfully.');
    })
    .catch(err => {
        console.log(err);
    });

...or build via CLI:

docma -c path/to/docma.json

Changelog

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

License

MIT.

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