Skip to content

Latest commit

 

History

History
 
 

zebra

README.md

Zebra — Template for Docma

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

Built with Docma using Zebra Template
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.