Environment Variables

Antora recognizes a number of environment variables that map to keys in the playbook. These environment variable can be used to configure Antora for different environments without having to modify the playbook file.

What is an environment variable?

An environment variable is a persistent variable (i.e., key=value pair) in your terminal which becomes available to all commands you execute at the prompt. This facility allows the behavior of commands to be altered based on which environment they are running in. For example, you may use an environment variable in a continuous integration (CI) or publishing environment to enable a behavior which may not be enabled by default.

You can output the current value of an environment variable using the echo command. In a Linux or macOS terminal, type:

$ echo $PATH

In the Windows command prompt, type:

$ echo %PATH%

And in Windows Powershell, type:

$ echo $env:PATH

Environment variables are not required for using Antora. You can configure these variables using the corresponding command line options or in your playbook with the matching keys.

Precedence

Environment variables take precedence over keys defined in the playbook file. However, the CLI option for a key takes precedence over the environment variable for that key.

If an environment variable (such as URL or https_proxy) is already set in your environment, and you wish to unset it temporarily when you run the antora command (i.e., a single invocation), you can do so using the env command:

$ env -u URL antora antora-playbook.yml

Another option is to run the antora command in a subshell. Inside a subshell, you can unset an environment variable without it affecting the environment of your main shell or operating system.

$ (unset URL; antora antora-playbook.yml)

Remember that environment variables take precedence over keys defined in your playbook file. So if you’re getting results you don’t expect, always check your environment variables to find out if they are the culprit.

Variables and formats

The following table summarizes the environment variables you can use to control the operation of Antora.

Variable Format Default Learn More

ANTORA_CACHE_DIR

String

<user cache>/antora

See cache_dir key and --cache-dir option

ANTORA_LOG_FAILURE_LEVEL

String

Not set

See failure_level key and --log-failure-level option

ANTORA_LOG_FILE

String

Not set

See file key and --log-file option

ANTORA_LOG_FORMAT

String

pretty if CI=true or terminal is interactive, otherwise json

See format key and --log-format option

ANTORA_LOG_LEVEL

String

warn

See level key and --log-level option

ANTORA_LOG_LEVEL_FORMAT

String

label

See level_format key and --log-level-format option. Only applies when the log format is json.

GIT_CREDENTIALS

String

Not set

See Private Repository Authentication

GIT_CREDENTIALS_PATH

String

Not set

See git credentials file path and --git-credentials-path option

GOOGLE_ANALYTICS_KEY

String

Not set

See Google Analytics key

http_proxy

String

Not set

See http_proxy key and --http-proxy option

https_proxy

String

Not set

See https_proxy key and --https-proxy option

no_proxy

String

Not set

See no_proxy key and --noproxy option. Note the name of the CLI option differs from the name of the environment variable and playbook key.

URL

String

Not set

See site url key and --url option