onury
This is the default template for Docma; with a side-bar symbols menu, search and navigation features; and a beautiful layout.
Usage
- Make sure you have the latest Docma installed.
- Although Zebra is installed together with Docma, you can still install/update this template via npm:
npm i docma-template-zebra -D - Set
template.pathto"default"or"zebra"or omit it in your build configuration (docma.json). - Configure and set
template.optionsas 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.jsonChangelog
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.