Publishing a UI Bundle

Antora needs one thing from the UI: a ZIP archive, or an unzipped directory, reachable through ui.bundle.url. The build of the UI project produces that archive, so publishing is just the question of where the file lives and how its address changes (or does not change) between releases. There are three practical answers.

Whichever you choose, the rules of the Antora loader are the same ones described in UI Bundle: a remote bundle must be a ZIP, it is cached by the signature of its URL, and a local path is read again on every run.

The Default UI project, and any UI forked from it, builds the archive with a single gulp task. The task lints the CSS and JavaScript, builds the assets and zips them, so a CI job needs nothing more than npm ci followed by npx gulp bundle. The details of the project are in Building a Custom UI.

Source: Antora Default UI: Build a UI project for local preview

The last lines of a real run in a copy of the Default UI clone (Node.js 24.21.0) were these. The task ends by printing the Antora option that would load the bundle it just wrote:

The file is build/ui-bundle.zip. The name is fixed by the project (the gulp file sets the bundle name to ui), so a release process that needs a version in the file name renames or uploads the file under another name; it is not something the UI build does for you. bundle:pack writes the same archive from the already built files, without linting or rebuilding; it is the last step of bundle.

The Default UI project itself is published this way, and it is the only publishing method the official documentation shows. Its .gitlab-ci.yml defines a job named bundle-stable that runs gulp bundle on the default branch and declares build/ui-bundle.zip as a job artifact. A job named bundle-dev does the same on every other branch, but marks the artifact to expire after one day. GitLab then serves the file from the job artifacts URL of the project.

A trimmed version of that pipeline for your own UI looks like this. The Default UI pins an old Node.js image; use a recent one for a new project.

Source: Antora Default UI: .gitlab-ci.yml

This file is an adaptation of the Default UI pipeline and was not run on GitLab. The consumer then points the playbook at the latest artifact of the job on the default branch. The address has the same shape for every build, so it must be a snapshot. This is the playbook form the Antora documentation uses for the reference UI:

Source: Antora docs: UI Bundle URL

Replace antora/antora-ui-default with the path of your own project and bundle-stable with the name of your job. The Antora documentation does not describe how long GitLab keeps job artifacts, so check the retention settings of your GitLab instance before relying on an artifact URL for a long time.

The official documentation does not describe publishing a custom bundle on GitHub. What follows is an inference from two documented facts: Antora accepts any HTTPS URL that returns a ZIP, and GitHub Releases serves release assets from stable URLs. A UI project hosted on GitHub can therefore publish its bundle as a release asset, which gives every release an address that never changes and a "latest" address that always moves.

GitHub documents two address forms for release assets: one that names the tag, and one that always resolves to the newest release.

Source: GitHub docs: Linking to releases

The workflow below builds the bundle whenever a tag starting with v is pushed and attaches it to a release created with the GitHub CLI, which is preinstalled on GitHub-hosted runners. It uses only the built-in GITHUB_TOKEN; no secret has to be created. The action versions are the ones used by the official Antora GitHub Pages example and by the publishing workflow of this repository.

Source: Antora docs: Publish to GitHub Pages (action versions), GitHub CLI manual: gh release create

The workflow file parses as valid YAML and its build steps (npm ci, npx gulp bundle) ran locally, but it was not executed on GitHub, so the release step is untested. To cut a release you tag and push:

The consuming playbook then picks one of the two address forms. A pinned version needs no snapshot because the URL changes with each release; the "latest" form needs snapshot: true, for the reasons explained in the next section.

Source: Antora docs: UI Bundle URL

Antora does not check a checksum of the bundle. If the integrity of the UI matters, publish a checksum next to the asset and verify it in your own build script before running Antora; that is outside what Antora offers.

Antora caches a remote bundle under a file name derived from its URL. As long as the URL stays the same, the cached file is used and nothing is downloaded. The snapshot key opts out of that rule for a URL whose content changes, but only when fetching is enabled, either with --fetch on the command line or with runtime.fetch: true in the playbook.

The behaviour was reproduced with Antora 3.2.1. Two bundles that differ only in the footer text (VERSION-ONE and VERSION-TWO) were served by a local HTTP server at one address, the cache was a fresh directory, and the footer of the built site was read after every run.

Three consequences follow, and they match the official page on the bundle URL.

The cache location depends on the operating system: $XDG_CACHE_HOME/antora or $HOME/.cache/antora on Linux, $HOME/Library/Caches/antora on macOS and $APPDATA/antora/Caches on Windows. It can be moved with --cache-dir, the ANTORA_CACHE_DIR variable or runtime.cache_dir. Deleting the folder is also a valid way to force a download, and is the first thing to try when a site still shows the old UI.

Source: Antora docs: Cache Directory

A local path behaves differently. The same experiment with url: ./local.zip and snapshot: true showed the new footer on the second run without --fetch, because Antora reads the file given by a filesystem path every time. The snapshot key is only needed for a remote bundle.

The playbook of this site does not download its UI at all. The custom UI is built in a separate project, and its output, ui-bundle.zip, is committed at the root of this repository, next to antora-playbook.yml. The relevant part of the playbook is short:

Source: Antora docs: UI Bundle URL

The path has no leading ./, so it is resolved against the current working directory. The nightly workflow runs npx antora antora-playbook.yml from the repository root, where the file lives, so the bundle is found. A path that starts with ./ would be resolved relative to the playbook file instead, which is more robust if the command is ever run from another directory.

The committed archive is about 324 KiB with 76 entries and no ui.yml. Its history in this repository has two commits touching it, which is the practical cost of the approach: every new bundle is a binary blob kept in the git history. Because the path is local, snapshot: true has no effect here; the official documentation says the key matters only for a remote bundle. It is harmless, and it would become useful the day the playbook switched to a remote URL.

A middle path is to keep the UI in its own repository, publish releases there, and let the documentation playbook name a versioned release URL. Updating the UI then becomes a one-line pull request in the documentation repository, and the history of the docs repository stays free of binary files.

The sequence below puts the pieces together for the GitHub release variant. The maintainer tags the UI project, CI builds and attaches the bundle, and the next documentation build downloads it, caching it by URL.

Figure: from tag to rendered site, with the cache lookup that decides whether the network is used.