Playbook Provider

In addition to the primary build, you may want to have a local, author-oriented preview build within a content branch. One way to do this is to create a dedicated playbook in each content branch and configure the Antora plugin in that branch to make use of it. However, this scenario quickly becomes a maintenance burden. That’s where the playbook provider comes in.

As an alternative to maintaining a playbook per content branch, you can configure the plugin to sideload or download a playbook template from the playbook branch and/or playbook repository. This allows you to centrally manage the playbook used for the local preview of a content branch. It’s even possible to use this template to configure the packages property in the plugin configuration as well as the version of Antora itself.

Set up a playbook template

To use the playbook provider, you first need to decide where the playbook template will live. It can be located at any path in any branch of any public repository on GitHub or GitLab. Start by committing and pushing that template to the repository.

Here’s an example of a per-branch playbook template for the Spring Security docs:

lib/antora/templates/per-branch-antora-playbook.yml

site:
  title: Spring Security Reference
content:
  sources:
  - url: ./..
    branches: HEAD
    start_path: docs
asciidoc:
  attributes:
    page-pagination: ''
    hide-uri-scheme: '@'
  sourcemap: true
urls:
  latest_version_segment: ''
ui:
  bundle:
    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
    snapshot: true

Retrieve a playbook template

The next step is to configure the plugin to retrieve the template when the antora task is run. Here’s an example that shows how to configure the playbook provider feature of the plugin to retrieve this playbook:

build.gradle

antora {
    playbookProvider {
        repository = 'spring-projects/spring-security'
        branch = 'docs-build'
        path = 'lib/antora/templates/per-branch-antora-playbook.yml'
        checkLocalBranch = true
    }
}

If the checkLocalBranch property is true, the plugin will attempt to copy the file from a local branch of the current repository (sideload). Otherwise, it will attempt to retrieve the file from the git repository using its raw git URL (download). It will save the file to the path specified in the playbook property, which defaults to antora-playbook.yml. However, if this file already exists locally, the plugin will skip the sideload/download step. To get a fresh copy, remove this file and the plugin will retrieve it again on the next run.

Declare packages in a playbook template

If the docs build depends on extension packages, such as @antora/collector-extension or @asciidoctor/tabs, you can declare these packages in the playbook template. You declare the packages in a magic comment line that begins with # PACKAGES. A package entry takes the form name@version, where name is the package name in the npm registry and version is an exact version, version tag, or range specifier. If the @version portion is absent, the version tag latest is used. Each package declaration is separated by a single space.

Here’s an example:

per-branch-antora-playbook.yml

# PACKAGES @antora/collector-extension@1.0.0-alpha.2 @asciidoctor/tabs

The plugin will detect this line in the playbook template and add these packages to the plugin configuration. If a package name already exists in the plugin configuration, the entry from the plugin configuration will be used.

You can also use the PACKAGES comment line to specify the version of Antora itself. This version is controlled through the package name antora. Here’s an example:

per-branch-antora-playbook.yml

# PACKAGES antora@3.2.0-alpha.2 @antora/collector-extension@1.0.0-alpha.2 ...

If the version of Antora is already specified in the plugin configuration, that version will be used instead.

By using the playbook provider, you can centrally manage the playbook used to generate a preview of the site in each content branch.