UI Bundle URL
A UI bundle is a ZIP archive that contains one or more UIs for a site. Antora fetches and loads a UI bundle when generating a site.
url key is required.
It’s configured under the ui and bundle keys in a playbook.
url key accepts a URL or filesystem path from where Antora can locate and fetch the site’s UI bundle.
ui: (1) bundle: (2) url: https://repo.org/path/to/a-ui-bundle.zip (3)
|1||Enter the parent key
Remember that the UI bundle must be a ZIP archive.
url key can be assigned from the CLI.
When the value of
url is a remote URL, Antora downloads and caches the ZIP archive the first time it runs.
ui: bundle: url: https://repo.org/path/to/a-ui-bundle.zip
On subsequent runs, Antora loads the bundle from the cache as long as the value of
url remains the same.
This saves Antora from having to download the bundle each time you generate your site.
In order to retrieve UI bundle updates without changing the
url value, you need to activate the
A UI bundle is cached based on the signature of the URL.
url value remains the same, but the archive it points to changes over time, the UI bundle needs to be identified as a snapshot with the
Otherwise, Antora won’t download the UI bundle again as long as it exists in the cache, even when
fetch is used.
snapshot key is mapped to the
By default, it’s deactivated (set to
snapshot is set to
true, Antora will download the UI bundle whenever
fetch is activated in the playbook or from the CLI.
ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true
If you’re using Antora’s reference UI bundle, you should mark it as a snapshot.
The snapshot key is only required if you’re referring to a remote bundle (which Antora caches by default). If you’re referencing a bundle from the filesystem, Antora will always use the file as specified.
url key can reference a local UI bundle using an absolute or relative filesystem path.
ui: bundle: url: ./../docs-ui/build/ui-bundle.zip
A relative path is expanded to an absolute path using the following rules:
If the first path segment is a tilde (
~), the remaining path is resolved relative to the user’s home directory.
If the first path segment is a dot (
.), the remaining path is resolved relative to the location of the playbook file.
If the first path segment is a tilde directly followed by a plus sign (
~+), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.
Here’s the path to the same UI bundle, but using an absolute path instead.
ui: bundle: url: /home/user/projects/docs-ui/build/ui-bundle.zip
start_path key is mapped to the
It accepts a the relative path inside the UI bundle from where Antora should start reading files.
This key is useful when a UI bundle packages multiple UIs (e.g., light, dark, etc.).
ui: bundle: url: /home/user/projects/docs-ui/build/ui-bundle-with-themes.zip start_path: dark
In this example, Antora will ignore all of the files in the UI bundle that fall outside the dark directory.