Allow modules that provide the generator functions to be specified in the playbook
As a complement to Antora extensions, it should be possible to specify a module that replaces any one of the built-in modules used by the site generator. This allows parts of Antora to be swapped out (interchangeable parts) without having to replace the site generator wholesale. The replacement would have to adhere to the same API of the original, which usually amounts to exporting a top-level function with the same parameters and return value.
The logical place to specify these modules is in the modules
key under the antora
category key in the playbook. The value of this key would be map. Each key is a predefined module name and the value is a require request Antora can use to locate and require the code. If no entry is present for a given module name, Antora will fall back to the preferred module.
Here's an example of how to replace the content aggregator module:
antora:
modules:
content-aggregator: antora-content-aggregator-with-lfs-support
The predefined module keys will follow the names of the preferred module without the @antora/
namespace (e.g., content-aggregator, asciidoc-loader, etc). These modules provide the generator functions. For example, the content-aggregator
module provides the aggregateContent
function. Some modules, like asciidoc-loader
, provide multiple functions.
The exception to this rule is the playbook builder. It's not possible to swap the playbook builder since the playbook builder itself is needed to read the playbook that provides the configuration. But this is a good thing because the playbook is the one part of Antora that is designed to be constant. Though we might rethink that assumption as we explore deeper into this issue.
To allow site generators other than the default site generator to use this key, we can leave the schema open ended.
We should also explore whether an Antora extension can modify the modules map to swap modules used by the site generator.