Register the Extension

Once the Antora Collector extension is installed, you need to register the extension with Antora. The extension can be registered in your Antora playbook or through the CLI.

Register in the playbook

To register the extension in your Antora playbook, add an entry to the playbook file (antora-playbook.yml) that specifies the name of the package under the antora.extensions key. Open your Antora playbook file and add the extension as follows:

antora-playbook.yml

antora:
  extensions:
  - '@antora/collector-extension'
# ...

The quotes are required around the package name because @ is a special character in YAML.

keep_worktrees key

By default, any temporary worktrees that Collector creates are removed as soon as it finishes running (after the contentAggregated event). If you want the keep the temporary worktrees indefinitely or until the specified event, you must set the keep_worktrees option on the extension.

antora-playbook.yml

antora:
  extensions:
  - register: '@antora/collector-extension'
    keep_worktrees: until:contextClosed
# ...

The accepted values for this key are true (keep worktrees indefinitely), false (don’t keep worktrees), or until:<event> (keep worktrees until the specified event, such as contextClosed). If keep worktrees is enabled, the worktrees will be unique by git repository and refname. Unless the value is true, Collector will ensure the worktree from a previous run is removed before creating it. The default setting can be overridden by the Collector instance.

This key only affects temporary worktrees, not worktrees used as a content source (which are always kept).

create_worktrees key

By default, Collector will only allocate a temporary worktree if the origin does not have one. The default create behavior for worktrees can be set on the extension itself using the create_worktrees key. If you want Collector to always allocate a worktree by default, set the create_worktrees option to always.

antora-playbook.yml

antora:
  extensions:
  - register: '@antora/collector-extension'
    create_worktrees: always
# ...

The accepted values for this key are auto (default) and always. The default setting can be overridden by the Collector instance.

Register from the CLI

Alternately, you can register the PDF extension at your discretion using the --extension CLI option of the antora command:

$ antora --extension @antora/collector-extension antora-playbook.yml

It’s possible to configure the extension when activating it through the CLI by adding an entry for it in antora.extensions in the playbook with the enabled key set to false. See Enable an Extension to learn more about how this works.

Now that you have registered the extension, you can configure Collector instances in the antora.yml files for your site.