Runtime Keys

The playbook keys configured under the runtime key manage Antora’s logger, as well as its console output, caching, and remote repository update behavior.

runtime key

The global log, console output, fetch, and cache directory properties are defined under the runtime key in a playbook file. These settings are applied to the Antora pipeline when it starts.

Example 1. antora-playbook.yml
runtime: (1)
  cache_dir: ./.cache/antora (2)
  fetch: true (3)
  log: (4)
    level: error (5)
1 Optional runtime key
2 Optional cache_dir key
3 Optional fetch key
4 Optional log key
5 Optional level key

The runtime key and the key-value pairs it accepts are optional. If runtime isn’t set in the playbook, Antora uses the default cache directory, fetch, and log settings. Alternatively, these keys can be assigned from the CLI or, except for fetch, using environment variables.

log key

The log key is optional. If you do set it in a playbook, you must nest it under the runtime key. The log key accepts a list of built-in key-value pairs that configure the log level (level), failure level (failure_level), and display format (format).

Example 2. antora-playbook.yml
runtime:
  log: (1)
    format: pretty (2)
    failure_level: warn (3)
    level: all (4)
1 The optional log key is nested under the runtime key.
2 The optional, built-in format key is nested under the log key.
3 The optional, built-in failure_level key is nested under the log key.
4 The optional, built-in level key is nested under the log key.

If level, failure_level, or format are set in the playbook, they must be nested under the log key. The level, failure_level, and format keys have default values that are automatically applied when Antora runs if they’re not explicitly defined in the playbook or using the corresponding the command line options or environment variables.

Available runtime keys

Runtime Keys Description Required

cache_dir

Specifies the directory where the remote content sources git repositories and UI bundles are cached.

No

fetch

When set to true, the fetch key refreshes the files in the cache each time Antora runs.

No

log.failure_level

Sets the log level tolerance that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code. Accepts the values warn, error, fatal, and none. The default value is fatal. The value none causes Antora to always exit with a zero exit code.

No

log.format

Sets the format of log messages. Accepts the values pretty and json. The default value is json in a CI environment and pretty in all other environments.

No

log.level

Sets the minimum severity threshold level that must be met for a message to be logged. Accepts the values all, debug, info, warn, error, fatal, and silent. The default value is warn. The value silent turns the logger off.

No