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

The 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 require key. 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.

Without configuration

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.

Example 1. antora-playbook.yml with extension

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.

With configuration

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 require key.

Example 2. antora-playbook.yml with extension specified using require key

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.