Configure a Run Action

The central focus of the Antora Collector extension is to generate and/or retrieve additional files to import. These files are typically generated by external commands, though they could also be retrieved. A run action can delegate to one or more external commands that generate additional content or metadata per content source root for your site.

You can configure one or more run actions using the run key. This page explains how to use the run key and the keys it accepts.

run key

A run action is configured using the run configuration key for the Collector instance. The run key must be nested under the collector key.

antora.yml

ext:
  collector:
    run:
      command: generate-files

If the value of the collector key is an array, the run key must be specified as a key on an array entry. The run key may be used in more than one entry in that array.

antora.yml

ext:
  collector:
  - run:
    - command: generate-files
    - command: generate-more-files
  - run: generate-all-the-files

Here’s a real world example that shows how to configure a run action:

antora.yml

name: colorado
title: Colorado
version: '5.6.0'
ext:
  collector:
    run:
    - command: gradlew -v
      local: true
    - ./gradlew --console rich generateContent

The value of the run key can be a map, an array, or a string. If the value is a string, the value is assumed to the value of the command key of a map. If the value is an array (i.e., a list of entries), each entry must be a string or a map consisting of built-in key-value pairs. In this case, each run entry is invoked sequentially, in the order specified in the array. If the value is a map (i.e., the leading - marker is dropped), it’s assumed to be a single-entry array.

Acceptable keys for the map value are listed in the table below.

Key Default Type Description

Key	Default	Type	Description
`command^*`	undefined	String (base call with optional space-separated list of arguments) or false	The external command to invoke.
`dir`	the worktree location	String (absolute path, path relative to start path if starts with `./`, or path relative to content source root)	The directory in which to run the command (the pwd for the command).
`local`	false	Boolean	Whether to run a local command or search the user’s PATH.
`shell`	false	Boolean	Whether to run the command in a shell.
`env`	undefined	Map or Array	Environment variables to set or unset in the context of the command.
`failure`	throw	String enum (ignore, log, or throw)	How to handle a non-zero exit value of the command.

command^*

undefined

String (base call with optional space-separated list of arguments) or false

The external command to invoke.

dir

the worktree location

String (absolute path, path relative to start path if starts with ./, or path relative to content source root)

The directory in which to run the command (the pwd for the command).

local

false

Boolean

Whether to run a local command or search the user’s PATH.

shell

false

Boolean

Whether to run the command in a shell.

env

undefined

Map or Array

Environment variables to set or unset in the context of the command.

failure

throw

String enum (ignore, log, or throw)

How to handle a non-zero exit value of the command.

* required

command key

The command key specifies a command to run for the current origin. This is the only required key for a run action.

The value of the command key is an external command string. The command string consists of a base call followed by an optional space-separated list of arguments. Alternately, the value can be false (boolean), in which case no command is invoked.

By default, the base call is assumed to be a system command (e.g., gradle), meaning it’s resolved from the current user’s PATH. (On Windows, the where command is used to search the PATH.)

If the local key is set to true, or the base call begins with ./, then it is resolved relative to the resolved value of the dir key. (Refer to the local key section for more details.) If the dir key is not specified, the value defaults to the location of the worktree. If the base call contains a directory separator, it’s resolved relative to value of the dir key even if the base call does not start with ./ (inherited system behavior). If the base call is a Node.js binary (e.g., node), the script path is resolved relative to the value of the dir key.

The command is run from the root of the worktree for the origin (not the start path) unless the dir key is specified. The dir key specifies an alternate working directory. (Use . to represent the start path).

run:
  command: ./gradlew --console rich generateContent

Only a single command is supported. Multiple commands cannot be chained together using chaining operators (;, &&, ||, etc.). If you need to run multiple commands, you need to specify them as separate entries in the value of the run key. You can handle when happens if a command fails using the failure key.

Quoting arguments

The base call or an argument only has to be enclosed in single or double quotes (i.e., quoted) if the value itself contains spaces or quotes. To pass an empty argument, use a pair of quotes with nothing in between (e.g., ""). If a quoted value contains a quote, that character can be escaped using a backslash. No other reserved shell characters need to be escaped by default (though you do need to be mindful of YAML escaping rules).

If the command only consists of a base call with spaces (e.g., "my command"), the value must be enclosed in quotes in such a way that the quotes are preserved by YAML. This means that you may need to enclose the command in two sets of quotes. A simpler solution, though, is to use the multi-line form (i.e., |- delimiter) to prevent the quotes from being dropped. This alternation is not often needed if the command has arguments.

Output

By default, both the stdout (output stream) and stderr (error stream) of the command are directed to the current terminal. The extension also logs the command it’s about to run at the info level.

The output and error lines may get interleaved differently compared to what was emitted by the command due to how Node.js works.

If you want to suppress the stdout and the info log message, you can set the runtime.quiet key in the playbook to true. If you also want to suppress the stderr, you can set the runtime.silent key in the playbook to true (or redirect stderr to /dev/null). If the command fails, the stderr lines are always appended to the error message.

Use the current Node.js

If the command begins with $NODE (or ${{env.NODE}}) followed by a space, that token will be replaced with the value of the NODE environment variable set on the Antora process, which defaults to the path of the Node.js executable used to run Antora.

run:
  command: $NODE generate-files.js

Similarly, if the command begins with the path of a JavaScript file (i.e., a file with the extension .js), the value of the NODE environment variable is inserted as the first command argument automatically.

run:
  command: generate-files.js

If the base call of the command is node (e.g., node generate-files.js), that’s not guaranteed to be the same Node.js runtime that was used to run Antora.

In order to use the npm or npx bin script provided by the current Node.js, you can use the $NPM or $NPX base call, respectively. For example:

$NPM run task-name

Alternately, you can use a relative reference from the value of the NODE environment variable For example:

${{env.NODE}}/../npm run task-name

Here’s an example of how to run an npm task defined at the root of the worktree.

run:
  command: $NPM run generate-files

This expression resolves the npm bin script that’s adjacent to the node binary in the Node.js installation.

dir key

The dir key defines the location from where the command is resolved and run (i.e., the pwd). The value of the dir key is a string path for a single directory. If the path is absolute, that value is used as is. If the path is . or starts with ./, the value is resolved starting from the start path. Otherwise, the path is resolved relative to the worktree directory.

run:
- command: generate-files.js
  dir: .

The current working directory is essentially switched for the duration of the command when the dir key is specified.

local key

If the local key is specified with the value true and the command is relative, the command is resolved relative to the resolved value of the dir key, or the worktree if the dir key is not specified. The local key can be set implicitly by prepending ./ to the base call in the command string.

run:
- command: gradlew -v
  local: true
- ./gradlew --console rich generateContent

Setting this key to true effectively disables looking for a global command on the current user’s PATH.

shell key

If the shell key is set to true, the command will be run in the operating system’s default shell. All arguments that contain reserved shell characters need to be quoted (e.g, "console.log(1)") or otherwise escaped. The command may also contain references to environment variables (e.g., $NODE), even on Windows. The list of available environment variables includes those defined on this run entry.

For Windows, the default shell is the value of the ComSpec environment variable, which is likely cmd.exe.

When the shell key is false (or not set) and the command has no file extension (e.g., gradlew), on Windows, Collector will search for a file that ends in .exe, .bat, or .cmd (in that order). If it finds a match, it will invoke that file instead. This is the default behavior in Windows when running in a shell.

To work around a policy restriction in Node.js on Windows, Collector will always run a batch script using the shell, even if the shell is not requested. However, no additional escpaing of arguments is required in this case as Collector will handle that task.

The value of the command key may include context variable expressions. The env context variable includes all environment variables added by the env key.

run:
  command: command-to-run --config-dir ${{env.HOME}}/.config/config-for-command

failure key

The failure key can be used to control what happens when the command fails. A failed command is one that exits with a non-zero exit value. If the value is ignore, the failure is silently ignored. If the value is log, the failure is logged at the error level. The log level can be tuned by appending it as a property on the log keyword (e.g., log.warn). If the value is throw (default), the error bubbles, which causes the execution of Antora to immediately stop, just like any other fatal error.

run:
  command: command-that-fails
  failure: log.warn

env key

The env key can be used to set (or unset) additional environment variables for the run command. The value of this key must be an array. Each entry consists of a name and value key. The name key specifies the name of the environment variable and the value key the value to assign to it. These environment variables are overlaid onto the environment variables from the Antora process (i.e., the parent process) and are scoped to the command.

The base env map inherits from the playbook.env context variable, which is the map of environment variables at the time Antora was launched. Collector automatically appends the NODE variable, which holds the value of process.execPath, as well as the PWD variable, which holds the resolved value of the dir key.

It’s also possible to express the environment variables in the form of a map. If the value is a map, each key is an environment variable name and the value its value.

env:
  refname: ${{origin.refname}}

However, versions of Antora before 3.2.0 automatically transform keys (and thus environment variable names) to camelCase form (e.g., THE_NAME becomes theName). Only lowercase environment variables without any separators are kept as is. Starting with Antora 3.2.0, the key is always preserved as entered, so you can safely use this form.

Use context variables

The value of the command key or the value of an environment variable can include references to context variables in the Antora runtime (e.g., origin). When used with environment variables, this feature provides a way to pass data from the Antora runtime to the external command. Currently, the supported context variables are as follows: origin (the content source origin on which Collector is running); playbook (the compiled Antora playbook); env (the map of environment variables).

The context variable reference must be enclosed in ${{ and }}, referred to as a context variable expression (e.g., ${{origin.refname}}). Dot notation can be used to access nested properties on the context variable (e.g., origin.refname). This notation provides safe navigation, which means if any property resolves to null, the whole value resolves to null.

If the value is null, the existing environment variable is unset. If the value is non-null, the value is coerced to a string.

The ${{env.PWD}} expression expands to the resolved value of the dir key, whereas the ${{playbook.env.PWD}} expression expands to the current directory at the time Antora was launched.

You can convert the value of the context variable to JSON or YAML by appending as json or as yaml, respectively, to the context variable reference (e.g., ${{origin as json}}.

antora.yml

name: colorado
title: Colorado
version: '5.6.0'
ext:
  collector:
    run:
      command: $NODE generate-files.js
      env:
      - name: ANTORA_COLLECTOR
        value: '1'
      - name: ANTORA_SITE_TITLE
        value: ${{playbook.site.title}}
      - name: ANTORA_COLLECTOR_ORIGIN
        value: ${{origin as json}}
    scan:
      dir: build/generated

The value may contain zero or more context variable expressions.