ADR: Move the buildPlaybook call outside the site generator
Attempts to integrate a logging infrastructure into Antora have revealed a possible violation of the playbook abstraction. Currently, the CLI arguments and environment variables are passed to the site generator, which immediately uses this data to build the playbook. However, this flow prevents the CLI from having access to the playbook. One consequence of this is that it makes it impossible to configure a custom site generator using the playbook. Another consequence is that the CLI cannot access the playbook to configure logging (rather, it has to be done in the site generator). The current flow also exposes the runtime environment directly to the site generator. As a consequence, the site generator can bypass the playbook, thus breaking the abstraction.
This ADR should explore the proposal of pulling the buildPlaybook step outside the site generator and passing that playbook to the site generator instead of passing the CLI arguments and environment variables. (The site generator could provide a fallback if called using its old API. We also might consider assigning the environment variable map to the playbook so that it can still be accessed, if necessary.)
While it's possible to configure the logging infrastructure after the existing buildPlaybook step in the site generator, the real benefit is that the playbook can now specify the custom site generator instead of requiring the user to pass it in via --generator
. The dependency on the playbook builder would also be consolidated to the CLI instead of split across the CLI and site generator.
One consequence of this change is that it will no longer be possible for a custom site generator to change how the playbook is built (unless it uses the playbook object to build a replacement playbook). However, it may be possible to update the playbook builder to accept a JavaScript file, which would essentially act as an extension point to run a different playbook builder. That would maintain the playbook abstraction while providing the same flexibility (all without having to provide a custom site generator).