UI Bundle URL
A UI bundle is a ZIP archive or directory that contains one or more UIs for a site. The only required file in the UI bundle is the default layout for pages (e.g., layouts/default.hbs) (and, if the 404 page is enabled, layouts/404.hbs as well). Antora automatically fetches and loads a UI bundle when generating a site.
url key is required.
This key is configured under the bundle key of the ui category key in a playbook.
url key accepts a URL or filesystem path from where Antora can locate and fetch the site’s UI bundle.
The filesystem path must point to a ZIP archive or a local directory where the ZIP archive has been extracted.
ui: (1) bundle: (2) url: https://repo.org/path/to/a-ui-bundle.zip (3)
|1||Enter the parent key
url key can be assigned from the CLI.
The UI bundle can be augmented using a supplemental UI.
When the value of
url is a remote URL, Antora downloads and caches the UI bundle the first time it runs.
In this case, the target must be a ZIP archive.
ui: bundle: url: https://repo.org/path/to/a-ui-bundle.zip
The UI bundle is cached based on the signature of the URL.
On subsequent runs, Antora loads the bundle from the cache as long as the value of
url remains unchanged.
This saves Antora from having to download the bundle each time you generate your site.
Antora won’t download the UI bundle again if it exists in the cache, even when fetch is enabled.
url value remains the same, but the archive it points to changes over time, the UI bundle needs to be identified as a snapshot to bypass this cache.
In order to retrieve UI bundle updates without changing the
url value, you need to enable the
snapshot key adjacent to the
By default, snapshot is not enabled (set to
When snapshot is set to
true, Antora will download the UI bundle whenever the fetch key under the
runtime category of the playbook is enabled.
The fetch key instructs Antora to retrieve updates (including the UI bundle snapshot).
ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true
|If you’re using Antora’s reference UI bundle, you should mark the bundle as a snapshot because its URL never changes.|
If you want to control when Antora retrieves updates, pass the
--fetch option when invoking the
To make this setting permanent, set the
runtime.fetch key in the playbook to
runtime: fetch: true
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 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
Here’s the path to the location where the UI bundle has been extracted (or it was organized with the same layout as an extracted archive).
ui: bundle: url: ./../docs-ui/build/ui-bundle-extracted
Loading the UI bundle from a local directory is a good way to debug the logic.
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.