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 pipeline.extensions key in the playbook file or specify it using the --extension CLI option. 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 using extension enablement.

Let’s register our extension in the playbook file so that we can see it in action. In its simplest form, the entry is the require request (i.e., path) to the script. We prefix the path with ./ to indicate that its location is relative to the playbook file.

Example 1. antora-playbook.yml with extension
pipeline:
  extensions:
  - ./my-extension.js

When you run Antora, you should now see a line like this in your terminal:

Antora is building the Example Docs.

You can also specify the extension to require using the explicit require key.

Example 2. antora-playbook.yml with extension specified using require key
pipeline:
  extensions:
  - require: ./my-extension.js

If you were to publish this extension to a package repository, then the require request would be the name of the package. 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.