[go: up one dir, main page]

Allow CLI to control extension load order when extensions are declared in playbook

Currently, the only way to configure an extension is to declare it in the playbook. However, by doing so, it implicitly influences the load order. We need a way to decouple these two mechanisms.

Extensions declared in the playbook are loaded first, in the order they are declared. Any additional extensions declared using the CLI are then loaded in order. If extensions have to be loaded in a specific order, this eventually leads to having to declare all extensions in the playbook.

It should be possible to control the load order of extensions using the CLI, even if those extensions are declared in the playbook. This can happen one of two ways. Either the order of the extensions specified using the CLI is always preserved, or there is a special flag like config_only (or enabled: config) that allows an extension to be declared in the playbook without influencing the load order.

Here's an example:

antora:
  extensions:
  - id: ./lib/content-review-extension.js
    require: ./lib/content-review-extension.js
    enabled: false
  - id: '@opendevise/antora-binary-files-extension-pack@content-review'
    require: '@opendevise/antora-binary-files-extension-pack'
    enabled: false
    object_storage:
      readonly: true
      url: https://gitlab.com/gadhs/pamms
      branch: files

We have to declare ./lib/content-review-extension.js in the playbook, even though it doesn't require any configuration, since it has to be loaded before the @opendevise/antora-binary-files-extension-pack.

antora --extension /lib/content-review-extension.js --extension @opendevise/antora-binary-files-extension-pack@content-review antora-playbook.yml

One way to avoid this problem would be to use the proposed flag:

antora:
  extensions:
  - id: '@opendevise/antora-binary-files-extension-pack@content-review'
    require: '@opendevise/antora-binary-files-extension-pack'
    enabled: config
    object_storage:
      readonly: true
      url: https://gitlab.com/gadhs/pamms
      branch: files

Now, whatever order is specified on the CLI will be honored.