Environment Variables

Antora recognizes a handful 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. This page introduces you to these environment variables and how they work.

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 CI / 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 and macOS terminal, you’d type:

$ echo $PATH

In the Windows command prompt, you’d type:

$ echo %PATH%

And in Windows Powershell, you’d type:

$ echo $env:PATH

If environment variables are not something you are comfortable using, note that they are not required for using Antora.

Precedence

Environment variables take precedence over keys defined in the playbook file, but get overridden by the CLI option for that same key.

Variables and formats

The following table summarizes the environment variables that Antora recognizes and can thus be used 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

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 and --google-analytics-key option

URL

String

not set

See site url key and --url option

Support for additional environment variables may be added in a future release.