Enable an Extension
By default, if you register an extension in the playbook file, Antora will enable it automatically.
One way to enable an extension only on request is to specify it using the CLI option (
However, that alone doesn’t allow you to provide configuration keys or influence the load order.
That’s where extension enablement comes into play.
You can register an extension in the playbook file, along with optional configuration, then tell Antora not to enable it.
You can then use the CLI option (
--extension) to enable it, and it will be registered relative to other extensions in the order listed in the playbook.
To prevent Antora from enabling an extension specified in the playbook file, set the predefined configuration key
enabled to the value
When Antora sees that the
enabled key has a value of
false, it will not register the extension.
antora: extensions: - require: ./my-extension.js enabled: false custom: value
You can use the
enabled key to quickly turn off an extension without having to remove it from the playbook.
More likely, though, you mark it this way so that it can be enabled using the CLI option.
However, in order to do that, you need a way to reference it.
That’s the purpose of the predefined configuration key
id key specifies a value you can reference using the
--extension CLI option to enable an extension that’s marked as not enabled in the playbook file.
First, let’s give our extension an ID:
antora: extensions: - id: my-extension require: ./my-extension.js enabled: false custom: value
Now we can now enable this extension from the CLI as follows:
$ antora --extension=my-extension antora-playbook.yml
Whereas normally the value of the
--extension CLI option is a require request, in the case when you are enabling an extension, the value is the ID of the extension entry in the playbook file.
If Antora can’t locate an entry with an ID that matches the value of the
--extension CLI option, it falls back to treating the value as a require request.