Register an Extension
An extension is inactive until it’s registered with Antora.
There are two ways to register an extension.
You can list it as an entry in the
extensions key under the
antora category key in the playbook file or specify it using the
--extension CLI option.
--extension CLI option adds entries to the
extensions key at runtime.
Once registered, Antora invokes the register function of the extension in the order it’s listed in the playbook file or passed to the CLI. The extensions in the playbook file are registered before the extensions passed to the CLI, though this order can be changed by enabling a registered extension on request.
extensions key is specified under the
antora category key in the playbook file.
The value of the
extensions key must be an array.
Each entry in the array is either a string or a map (key/value pairs).
When the value is a string, the value is assumed to be a require request (i.e., path or module name) that resolves to the extension script.
When the value is a map, the require request must be specified using the
Using a map leaves room for additional configuration keys, both predefined (like
enabled) and custom.
If you were to publish the extension to a package repository, then the require request would be the name of that package (i.e., its module name). In that case, ensure that the package is configured as a dependency of the playbook project so that Node.js fetches it. Antora doesn’t download npm packages for you.
Let’s register our extension in the playbook file so we can see it in action. In its simplest form, the extension entry is the require request (i.e., path) to the extension script.
antora: extensions: - ./my-extension.js
We prefix the path with
./ to indicate that its location is relative to the playbook file.
See the @antora/user-require-helper usage to learn how Antora resolves require requests in the playbook file.
When you run Antora, you should now see a line like this in your terminal:
Antora is building the Example Docs.
If you need to specify configuration settings for the extension, then you must change the entry type from a string to a map.
When making this change, the require request must now be specified on the
antora: extensions: - require: ./my-extension.js optional_behavior: true
By using a map, additional keys can be added as siblings of the
require key in order to pass configuration to the extension.
You can find an example of how to use these additional keys to configure an extension on the Configure an Extension page.
Our next step is to add event listeners to our extension.