Antora Default UI

This project produces the default UI bundle for documentation sites generated with Antora. It contains the UI assets (page templates, CSS, JavaScript, images, etc.) and a Gulp build script. The build can be used to preview the UI locally (featuring live updates), or to package it for consumption by the Antora site generator.

This documentation explains how to use this project to set up, customize and manage a UI for a documentation site generated with Antora. After reading it, you’ll be able to:

  • Understand how an Antora UI project is structured.

  • Set up your environment to work on the UI project.

  • Launch a preview server to visually inspect the UI.

  • Adopt a development workflow to share and accept changes to the UI.

  • Package a UI for your documentation site that Antora can use.

1. File type and technology overview

The Antora UI consists of the following file types that are used to structure and style the documentation site pages generated by Antora.

  • Handlebars “page” templates (layouts, partials, and helpers)

  • CSS (enhanced using PostCSS)

  • JavaScript (UI scripts)

  • Images / Graphics (specific to the UI)

  • Fonts

  • Sample content for previewing the UI (HTML and UI model)

To understand how the UI works, let’s begin by surveying the primary technologies used by the UI.

Handlebars (file extension: .hbs)

Handlebars is a “logic-less” templating engine used to create HTML from template files. Templates contain placeholders (i.e., mustache expressions like {{{page.title}}}) into which content is injected from a model. They also accommodate simple logic expressions for repeating content or including it conditionally (e.g., {{#each navigation}}) as well as partials (e.g., {{> header}}).

Gulp (script file: gulpfile.js/index.js)

Gulp is a build tool for JavaScript projects. It configures a collection of tasks that can be used to perform automated tasks such as compiling files, running a preview server, or publishing a release.

npm (command: npm)

npm manages software packages (i.e., software dependencies) that it downloads from npmjs.com. Software this project uses includes libraries that handle compilation as well as shared assets such as font files that are distributed as npm packages. npm is part of Node.js.

package.json

This file keeps track of the dependencies (described using fuzzy versions) that npm (or Yarn) should fetch.

package-lock.json

This file contains a report of which dependencies npm resolved. This information ensures that dependency resolution is reproducible.

node_modules/

A local cache of resolved dependencies that npm (or Yarn) fetches.

PostCSS

This project does not use a CSS preprocessor such as Sass or LESS. Instead, it relies on normal CSS which is enhanced by a series of postprocessors. The most common postprocessor backports newer CSS features to older browsers by adding properties with vendor prefixes.

2. UI project versus UI bundle

The UI project, the master branch of a git repository, contains the recipe and raw materials for creating an Antora UI bundle. It includes a build, source files, project files, and dependency information. This is your development workspace.

The UI bundle, a distributable archive, provides pre-compiled (interpreted, consolidated, and/or minimized) files that are ready to be used by Antora.

2.1. UI project repository structure (master branch)

You should think of the UI project’s master branch as your UI workspace. It contains the recipe and raw materials for creating a UI, including a build, source files, project files, and dependency information.

Here’s how the files are structured in the UI project:

README.adoc
gulpfile.js/
  index.js
  lib/
  tasks/
package.json
package-lock.json
src/
  css/
    base.css
    breadcrumbs.css
    ...
  helpers/
    and.js
    eq.js
    ...
  img/
    back.svg
    caret.svg
    ...
  layouts/
    default.hbs
    404.hbs
  partials/
    article.hbs
    breadcrumbs.hbs
    ...
  js/
    01-navigation.js
    02-fragment-jumper.js
    ...
    vendor/
      highlight.js
preview-src/
  index.html
  ui-model.yml

A Gulp build is used to compile and assemble the UI project files into a UI bundle.

2.2. UI bundle structure (releases)

The UI bundle—​a distributable archive—​provides files which are ready to be used by Antora.

When the UI project files are built by Gulp, they are assembled under the public directory. Since the public directory is generated, it’s safe to remove.

The contents of the UI bundle resembles the UI project’s master branch contents, except the bundle doesn’t contain any files other than the ones that make up the UI. This is the content that is used by Antora.

css/
  site.css
font/
  ...
helpers/
  and.js
  eq.js
  ...
img/
  back.svg
  caret.svg
  ...
layouts/
  default.hbs
  404.hbs
partials/
  article.hbs
  breadcrumbs.hbs
  ...
js/
  site.js
  vendor/
    highlight.js

Some of these files have been compiled or aggregated, such as the stylesheets and JavaScript. The benefit of building the UI files is that the files can be optimized for static inclusion in the site without that optimization getting in the way of UI development. For example, the UI build can optimize SVGs or add vendor prefixes to the CSS. Since these optimizations are only applied to the pre-compiled files, they don’t interfere with the web developer’s workflow.

3. UI compilation and generator consumption overview

The purpose of an Antora UI project is to get the UI files into a state that Antora can use and to make it reusable.

The UI is served statically in a production site, but the UI’s assets live in a source form in a UI project to accommodate development and simplify maintenance. When handed off to the Antora pipeline, the UI is in an interim, pre-compiled state. Specifically, the master branch of the git repository contains the files in source form while releases are used to distribute the files in pre-compiled form.

The responsibility of compiling the UI is shared between a UI project and Antora. The UI project uses a local build to pre-compile (i.e., interpret, consolidate, and/or minimize) the files. The pre-compiled files are agnostic to Antora’s content model, relieving the generator from having to deal with this part. It also allows the UI to be reused.

The UI project build then packages the UI into a bundle, which the UI Loader in Antora consumes. Antora grabs the bundle, extracts it into a UI catalog, and takes compilation to completion by weaving the Antora’s content model into the Handlebars templates to make the pages and auxiliary data files. Antora then copies the remaining UI assets to the site output.

Now that you have an overview of the files that make up the UI and how it gets assembled, let’s go over how to set up the project, build the UI, and preview it.