Building a Custom UI

The Default UI repository (https://gitlab.com/antora/antora-ui-default) is an archetype: a complete, working UI together with the build that turns its sources into a bundle. Its documentation describes it as the starting point for a custom UI, either by working directly in a clone or by forking it. The alternative to a full fork is to keep the stock bundle and override single files with a supplemental UI, which is covered in Supplemental UI. A fork pays off when you change many files, want a linted and versioned bundle, or want to preview templates before they ever meet real content.

The Default UI is published under the MPL-2.0 license (the LICENSE file and the documentation both say so), so keep the license file and the notices in your copy and read the terms before redistributing a modified bundle.

The UI build is a Node.js project, so you need the following tools.

Checking the tools:

Source: Antora Default UI docs: Prerequisites

Clone the project, change into it and install the dependencies. npm ci installs exactly what package-lock.json records; the official instructions use npm i, which also works and updates the lock file if a dependency has to be resolved again. Commit the lock file whenever it changes so the build stays reproducible.

Source: Antora Default UI docs: Set up a UI project

The last command lists the tasks the build supports. This is the output seen with this version of the project:

The official page lists the same tasks without pack, which the gulpfile.js marks as deprecated in favor of bundle. During npm ci, recent npm versions print a warning that install scripts of some packages (fsevents, jpegtran-bin and others) were skipped. The build still ran, but gulp-imagemin then reported that it could not load its optipng plugin and minified the seven images with the plugins that did load. If you need every image optimizer, approve the install scripts as the npm message explains.

If you want to keep your changes, work in a fork or on a branch of your own: the project’s documentation describes a workflow of a development branch, a pull request and an automated release triggered by merging to the default branch, which only applies to the Antora maintainers' own project. For your own UI, a plain Git repository is enough.

The folders that matter, as found in the clone, are these.

The folder src/ becomes the bundle. The bundle root contains css, font, helpers, img, js, layouts and partials; the font files come from the @fontsource packages, not from src/. How each of those folders is used by Antora is explained in Templates and UI Model, Helpers and Stylesheets, Fonts and Static Files.

Source: Antora Default UI docs

Run every task from the project folder with npx gulp <task>. The following table summarizes what the gulpfile.js of this version does for each one.

Source: Antora Default UI docs: Build and preview the UI

npx gulp lint should finish silently apart from the task log. To see what a failure looks like, a line with an unused variable and an extra semicolon was appended to src/helpers/year.js (and reverted afterwards):

Because bundle runs lint before build, a bundle cannot be produced while the style rules are violated. Run npx gulp format to fix JavaScript formatting automatically.

Running npx gulp bundle cleans, lints, builds and zips. It took about 1.4 seconds in the scratch project and printed, at the end, the ready-made Antora option for the file:

The result is build/ui-bundle.zip with about 74 entries (403 kB uncompressed): css/site.css, the Roboto web fonts, js/site.js, js/vendor/highlight.js, the helpers, layouts, partials and images. The bundle has no ui.yml; that optional file is described in Stylesheets, Fonts and Static Files. The task prints the line Antora option only when the CI environment variable is not set.

Preview and real-site checks complement each other, and the loop below uses both.

The figure above shows that the cheap preview comes first and the real Antora build is the gate before you publish.

The preview cannot show real content, multiple versions or the real navigation, so build the actual site with the new bundle. The Antora playbook key ui.bundle.url accepts a local path as well as a URL, and the command line option --ui-bundle-url overrides it for a single run, which is the quickest way to test without touching the playbook.

The following example changes the footer for the Pocket Units documentation. First the partial in the UI project is edited:

Source: Antora Default UI docs: Template customization

Then the bundle is built and the Pocket Units site is generated with it. Both commands are run from the folders shown:

Source: Antora docs: Specify a UI bundle

The generated page pocket-units/2.0/index.html then contained the new text, which confirms the full chain:

In this run the command was started from the folder that holds the playbook, so the relative path worked the same whether it came from the playbook key or from the command line option. If you start Antora from another folder, use an absolute path to avoid ambiguity.

Antora needs the default layout. When a bundle without layouts/default.hbs was used, the build stopped immediately:

The 404 layout is optional for Antora itself. A bundle without layouts/404.hbs built successfully and the generated site simply had no 404.html. The preview behaves differently, because it renders preview-src/404.adoc with the 404 layout; delete or adapt that file too if you remove the layout.

Other points that commonly trip people up: