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:
extensions:
- '@antora/collector-extension'
# ...
The quotes are required around the package name because @ is a special character in YAML.
|
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.
Global configuration defaults
The extension entry in the playbook provides a place to set global configuration defaults. These configuration keys are described in the section below. Each of these values can be overridden by the configuration for a Collector instance.
| The playbook must be used to set global configuration defaults even when the extension is registered from the CLI. |
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:
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:
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.