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 retrieve a playbook template from the playbook branch (or wherever you choose to store it). 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 the plugin installs and set the version of Antora itself.

Configuration parameters

The nested parameters that the playbookProvider parameter recognizes are defined in the following table.

Name Type Default Description

<host>

String

github

The git host of the remote repository. Not needed if the tryLocalBranch parameter is only. Only the following values are accepted: github, github.com, gitlab, gitlab.com, bitbucket, bitbucket.org

<repository>

String

-

The URL path of the repository on the git host (without the .git file extension). Not needed if the tryLocalBranch parameter is only. Both the host and repository can be specified in this parameter using the syntax host:repository.

<branch>

String

docs-build

The branch of the repository where the playbook template is located. The value HEAD can be used to refer to the current branch of the current repository if the tryLocalBranch parameter is only or the default branch of the repository otherwise.

<path>

String

antora-playbook-template.yml

The path in the specified branch of the repository where the template is located. Both the branch and path can be specified in this parameter using the syntax branch:path.

<tryLocalBranch>

String

false (if repository is specified)
only (if repository is not specified)

Whether to look for the playbook in the local repository before looking for it in the remote repository. Allowable values are: true (or first), only, false (or never).

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, GitLab, or Bitbucket. It can also be located in the local clone of the repository that contains the build using the Antora Maven plugin. Start by committing and pushing that template to the repository.

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

per-branch-antora-playbook-template.yml
site:
  title: Antora Docs
  start_page: antora::index.adoc
content:
  sources:
  - url: ./.. # assumes Maven project is located in docs directory
    branches: HEAD
    start_path: docs
asciidoc:
  attributes:
    idprefix: '@'
    idseparator: '-@'
    page-pagination: ''
    table-frame: 'none@'
    table-grid: 'rows@'
    hide-uri-scheme: '@'
urls:
  latest_version_segment_strategy: redirect:to
  latest_version_segment: latest
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Retrieve a playbook template

The next step is to configure the plugin to retrieve the playbook template when the antora:antora goal is run.

Here’s an example that shows how to configure the playbook provider to retrieve the playbook template from the previous example if it were located in the main branch of the docs.antora.org repository.

pom.xml
<configuration>
  <playbookProvider>
    <host>gitlab</host>
    <repository>antora/docs.antora.org</repository>
    <branch>main</branch>
    <path>per-branch-antora-playbook.yml</path>
    <tryLocalBranch>first</tryLocalBranch>
  </playbookProvider>
</configuration>

This configuration can be abbreviated as follows:

pom.xml
<configuration>
  <playbookProvider>
    <repository>gitlab:antora/docs.antora.org</repository>
    <path>main:per-branch-antora-playbook.yml</path>
    <tryLocalBranch>first</tryLocalBranch>
  </playbookProvider>
</configuration>

If the tryLocalBranch parameter is first or only, the plugin will attempt to copy the template file from the specified branch in the local repository (i.e., sideload). If the plugin cannot sideload the template, and tryLocalBranch is not only, it will attempt to retrieve the file from the git repository using its raw git URL (i.e., download). The playbook provider will save the file to the path provided-antora-playbook.yml adjacent to pom.xml.

If you want the behavior of a provided playbook, but don’t want to retrieve it from a remote repository, you can commit it adjacent to the pom.xml file and refer to it using the path parameter with the syntax HEAD:<path>. In this case, the tryLocalBranch parameter should be only and the repository parameter should not be specified. The playbook will still be copied and processed, but it’s not shared across branches.

If the template file already exists locally, the plugin will skip the retrieval step. That means you can modify the file after it’s retrieved to tune how Antora runs. To get a fresh copy, remove the cached file and the plugin will retrieve it again on the next run.

Declare packages in a playbook template

When the playbook provider is used, the package.json file is ignored as well as any packages defined using the packages parameter. The reason for this is that the playbook template is intended to orchestrate the Antora run.

If the docs build depends on extension packages, such as @antora/lunr-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/lunr-extension@1.0.0-alpha.8 @asciidoctor/tabs

The plugin will detect this line in the playbook template and add these packages to the plugin configuration. The Maven project can still declare additional packages using the additionalPackages parameter in the plugin configuration. If a package name is already listed in additionalPackages, that entry will take precedence.

Set the Antora version

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

per-branch-antora-playbook.yml
# PACKAGES antora@testing @antora/lunr-extension@1.0.0-alpha.8 ...

This feature only works if the version parameter is not specified in the plugin configuration. If the version of Antora is specified, that version will take precedence.