Runtime Configuration

On this page, you’ll learn:

  • How to configure the cache directory.

  • How to fetch updates to content sources and UI.

Cache directory

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.

Default cache directory

The default location for the cache varies by operating system.

  • Linux: $XDG_CACHE_HOME/antora (or $HOME/.cache/antora if $XDG_CACHE_HOME is not set)

  • macOS: $HOME/Library/Caches/antora

  • Windows: $APPDATA/antora/Caches

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.

Specify a cache directory

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.

Fetch updates

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 true.

runtime:
  fetch: true
Prior to Antora 2, the name of this key was pull. Although that key is still recognized, it’s considered deprecated.

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 site.yml

The --fetch CLI switch sets the fetch key described in this section to true, overridding any value set in the playbook file.

Setting the fetch key to true activates two behaviors in Antora:

  1. Run a fetch operation on all cloned repositories (content sources that are remote)

  2. Download the remove UI bundle anew if it’s marked as a snapshot

Enable the fetch key whenever you want to retrieve updates to the remote content sources and/or remote UI bundle snapshot.