Work with the Handlebars Templates

Antora combines the Handlebars templates with the converted AsciiDoc content and other UI model data to make the pages in the site. These “logic-less” templates are mostly HTML with some special mustache tags sprinkled in where content should 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. The model can be accessed by enclosing path expressions in mustaches, which are {{ and }} or {{{ and }}} (e.g., {{{page.title}}}). The double mustaches escape the value for HTML, whereas triple mustaches insert the value as is.

If the mustaches are preceded by a backslash (e.g, \{{), the expression will be disabled. This often comes up when constructing URLs. To avoid this problem, you should use forward slashes in URLs instead of backslashes.

When {{ is immediately followed by >, that invokes a partial (from the partials directory) and inserts the result (e.g., {{> head}}. In other words, that’s not a model reference like the other mustache expressions.

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 (top-level variables in bold)
Name Description

site

Information about the site.

site.url

The base URL of the site, if specified in the playbook.

site.path

The pathname (i.e., subpath) of the site.url under which the site is hosted (e.g., /docs). This value is empty if site.url is not defined, has no path segment, or matches /. Can be dropped from the site.url value using a helper (e.g., deleteSuffix site.url site.path) Can be prepended to page.url to create a root-relative URL for a page (e.g., {{{site.path}}}{{{page.url}}}). (since Antora 2.1)

site.title

The title of the site.

site.components

A map of all the components in the site, keyed by component name. Properties of each component include name, title, url, latest, and versions. Properties of each version include name (since 2.3), version, displayVersion, prerelease (if set), title, url, asciidoc (since 2.3), and navigation. The navigation property on each version provides access to the navigation menu for that component version.

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 in HTML format (often used as the primary heading). This value may include inline HTML elements and XML character references.

page.contents

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

page.attributes

Any AsciiDoc document attribute prefixed with page-. The page- prefix is dropped from the name used in this model. For example, the value of the document attribute named page-support-phone can be accessed via the UI model using page.attributes.support-phone. Page attributes can be defined per page in the AsciiDoc document header (e.g., :page-support-phone: +1 212-555-1234) or globally in the playbook under the key asciidoc.attributes. The page- prefix is used to isolate page-related attributes from the numerous other document attributes in AsciiDoc.

page.author

The first author of the document, if one or more authors are specified in the AsciiDoc header.

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, url, latest, and versions.

page.componentVersion

Information about the component version for the current page. Properties include name (since 2.3), version, displayVersion, prerelease (if set), title, url, and asciidoc (since 2.3).

page.module

The name of the module for the current page.

page.relativeSrcPath

The path of the current page relative to the pages directory in the current module (since 2.3).

page.version

The name of the version for the current page.

page.displayVersion

The name of the display 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.latest

The entry from page.versions that corresponds to the latest version available of this page. The latest page may not come from the latest version of the component (if the page is missing in that version). This property is not set if this page is in a versionless component.

page.breadcrumbs

An array of breadcrumb items that represent the current selection in the navigation tree. Includes text-only and external items.

page.navigation

The hierarchical navigation menu for the component version of 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. The canonicalUrl is only set if site.url is set. If there are multiple versions of the component, the canonical URL is the qualified URL of the most recent version of the page (excluding any prerelease versions). If there’s only a single version of the component, the canonical URL is the qualified URL of the current page.

page.editUrl

The URL to edit the current page (i.e., activates the web-based editor on the git host). This value is derived automatically for the hosts github.com, gitlab.com, pagure.io, and bitbucket.org, even if the repository is private. If the host is not recognized, or you want to customize the value, you can use the edit_url key on the content source in the playbook.

The default UI shows an "Edit this Page" link that points to this URL unless the repository is private (i.e., page.origin.private is true) or page.fileUri is set. You can force this link to be shown by setting the environment variable FORCE_SHOW_EDIT_PAGE_LINK (e.g., FORCE_SHOW_EDIT_PAGE_LINK=true) or by customizing the logic in the UI template.

page.fileUri

The local file:// URI to edit the current page if the page originates from the local filesystem (i.e., the worktree).

If this property is set, the default UI shows an "Edit this Page" link that points to this URI (instead of the page.editUrl value) unless the CI environment variable is set (e.g., CI=true). When the CI environment variable is set, the default UI ignores this property (since linking to a local file:// URI in a published site doesn’t make any sense).

page.origin.private

This value will be true if the repository requires authentication or the repository URL embeds credentials. In the default UI, if this value is true, the "Edit this Page" link is disabled. A quick way to force this property to be true (even if the repository is public) is to begin the content source URL in the playbook with empty credentials, as in https://@. Then, the "Edit the Page" link will not appear.

page.home

Indicates whether the current page is the start (aka home) page of the site.

page.layout

The page layout for the current page.

page.next

The next reachable page in the navigation tree (skips past text-only and external items).

page.previous

The previous reachable page in the navigation tree (skips past text-only and external items).

page.parent

The parent page in the navigation tree (skips past text-only and external items).

env

The map of environment variables (sourced from process.env).

siteRootPath

The relative path to the root of the published site.

uiRootPath

The relative path to the root directory of the UI.

antoraVersion

The version of Antora used to build the site (specifically the version of the @antora/page-composer package).

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 (top-level variables in bold).

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