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.
`on_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.

on_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 on_failure key.

Quoting arguments

An argument only has to be enclosed in single or double quotes (i.e., quoted) if the value itself contains spaces or quotes. To make an empty argument, use a pair of quotes with nothing in between (e.g., ""). If a quoted value contains a quote, that quote 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).

Output

By default, both the stdout (output stream) and stderr (error stream) of the command are directed to the current terminal. If you want to suppress the stdout, you can set the runtime.quiet key in the playbook to false. It’s not currently possible to suppress the stderr.

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 provided by the current Node.js, you can use the following expression:

${{env.NODE}}/../npm

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

run:
  command: ${{env.NODE}}/../npm generate

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. In this case, all arguments that contain reserved shell characters need to be quoted (e.g, "console.log(1)"). The command may also contain references to environment variables (e.g., $NODE), including those defined on this command entry.

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.

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

on_failure key

The on_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 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.

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.

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.

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.