Work with the Handlebars Templates

Antora combines the Handlebars templates with the converted AsciiDoc content to make the pages in the site. These “logic-less” templates are mostly HTML with some special mustache tags sprinkled in where content is to be inserted.

What do the templates do?

The layout templates, which are stored in src/layouts/, provide the main page structure. The partial templates, in src/partials/, fill in different regions of a page, such as the navigation and footer.

The templates read from a model that’s populated by Antora. Places in the template where the model is read are enclosed in {{ and }} markers or {{{ and }}}, aka mustaches (e.g., {{{page.title}}}). Double mustaches escape the content, whereas triple mustaches insert the content verbatim. When the {{ is immediately followed by >, that’s where the result of a partial is inserted (e.g., {{> head }}.

Template variables

This model is not final. Variable names and purposes may change.

Here’s an overview of the available UI model:

Table 1. Variables available to the Handlebars templates
Name Description

site

Information about the site.

site.url

The base URL of the site, if specified.

site.title

The title of the site.

site.components

A collection of all the components in the site.

site.ui

Information about the site UI.

site.ui.defaultLayout

The default page layout used for this site.

site.ui.url

The absolute base URL of the UI.

page

Information about the current page.

page.title

The page title (also used as the primary heading).

page.contents

The main article content in HTML format. Sourced from AsciiDoc and converted to HTML by the Asciidoctor processor.

page.attributes

AsciiDoc header attributes that are prefixed with page-. The page- prefix is dropped from these names.

page.description

The text of the description attribute in the AsciiDoc header, if specified.

page.keywords

A comma-separated list of keywords defined in the AsciiDoc header, if specified.

page.component

Information about the component for the current page. Properties include name, title, and versions.

page.componentVersion

Information about the component version for the current page. Properties include name, title, and url.

page.module

The name of the module for the current page.

page.version

The name of the version for the current page.

page.versions

All versions of the current page, including the current page. Each entry has the properties url, string, and missing.

page.breadcrumbs

An array of breadcrumb items that represent the current selection in the navigation tree.

page.navigation

A collection of navigation links for the current page. Each navigation item contains the property content as well as the optional properties url and (child) items.

page.url

The URL for the current page. This value is a root-relative path. It’s often used as the base URL to generate relative URLs from this page.

page.canonicalUrl

The canonical URL for the current page. If there are older versions of the page, the canonical URL is the URL of the latest version.

page.editUrl

The URL to edit the current page, typically on GitHub.

page.home

Indicates whether the current page is the home page of the site.

page.layout

The page layout for the current page.

page.next

The next logical page in the navigation tree.

page.previous

The previous logical page in the navigation tree.

page.parent

The parent page in the navigation tree. Will resolve to grandparent if parent item is not a page.

uiRootPath

The path to the root directory of the UI.

This model is likely to grow over time.

Modify a template

Let’s consider the case when you want to add a new meta tag inside the HTML head.

First, make sure you have set up the project and created a development branch. Next, open the file templates/partials/head.hbs and add your tag.

<meta class="swiftype" name="title" data-type="string" content="{{page.title}}">

Each template file has access to the template model, which exposes information about the current page through variable names. The variables currently available are listed in Variables available to the Handlebars templates.

Save the file, commit it to git, push the branch, and allow the approval workflow to play out.