On this page, you’ll learn:
How to configure the cache directory.
How to fetch updates to content sources and UI.
The first time Antora runs, it will cache remote git repositories and remote UI bundle. On subsequent runs, Antora will attempt to resolve remote resources from the cache instead.
This section explains where the cache is located by default and how to configure the location of the cache.
The default location for the cache varies by operating system.
Linux: $XDG_CACHE_HOME/antora (or $HOME/.cache/antora if
$XDG_CACHE_HOMEis not set)
Before downloading remote resources, Antora will first look for those resources in the cache folder, which maps to the user’s cache folder by default. If you want to instruct Antora to update the cache, configure Antora to fetch updates. Another option is to locate the Antora cache directory on your system and delete it.
The cache directory can be specified using the cache dir key (
cache_dir) under the
runtime category in the playbook.
The key specifies the directory where the remote repositories should be cloned and the remote UI bundle should be downloaded.
The key accepts a relative or absolute filesystem path.
runtime: cache_dir: ./.cache/antora
In this case, the value resolves to the folder .cache/antora relative to the location of the playbook file.
We know the the resolved location is relative to the playbook file because it starts with
The resolution rules for
cache-dir are the same as for any path in the playbook.
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 tilde plus (
~+), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.
As previously stated, the first time Antora runs, it caches the remote git repositories and remote UI bundle. On subsequent runs, Antora looks for these resources in the cache folder by default (effectively running offline).
You can tell Antora to refresh the cache by setting the
fetch key under the
runtime category to
runtime: fetch: true
Prior to Antora 2, the name of this key was
However, you don’t have to modify the playbook file directly to set this key.
Most of the time, you’ll just use the
--fetch CLI switch.
$ antora --fetch antora-playbook.yml
--fetch CLI switch sets the
fetch key described in this section to
true, overriding any value set in the playbook file.
fetch key to true activates two behaviors in Antora:
Run a fetch operation on all cloned repositories (content sources that are remote)
Download the remote UI bundle again if it’s marked as a snapshot
fetch key whenever you want to retrieve updates to the remote content sources and/or remote UI bundle snapshot.