Playbook Configuration Schema

On this page, you’ll learn:

  • How to structure an Antora playbook.

  • The role of each playbook key.

  • The values each playbook key accepts.

Playbook file structure

Here’s an example of a playbook file.

site: (1)
  title: Demo Docs Site (2)
  url: https://demo.antora.org (3)
  start_page: demo-component-b::index (4)
  keys: (5)
    google_analytics: 'XX-123456' (6)
content: (7)
  sources: (8)
  - url: https://gitlab.com/antora/demo/demo-component-a.git (9)
    branches: master (10)
    start_path: docs (11)
ui: (12)
  bundle: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable (13)
  start_path: dark-theme (14)
  default_layout: base (15)
  output_dir: _dark (16)
output: (17)
 clean: false (18)
 dir: releases (19)
 destinations: (20)
 - provider: archive (21)

Let’s explore the purpose and usage of each key and its values.

Site keys

The site’s global properties are defined under the site category in the playbook schema. Antora applies these properties to the whole site when it is generated.

title

The title of the documentation site.

Learn more:

url

The url key is the base URL of the published site.

Learn more:

start_page

You can use a page from a documentation component as the index page for your site. The start page key accepts a page ID as a value.

Learn more:

keys

The account keys for site-wide services such document search tools and Google Analytics.

google_analytics

The google_analytics key associates a Google Analytics account with the site.

Learn more:

Content and sources keys

The content category contains an array of source repository specifications. These source repository specifications are arranged under the sources category.

The sources key contains the list of git repository locations, branch name patterns, and other repository properties that Antora uses when aggregating the site content.

url

The url key tells Antora where to find a documentation component’s repository. The key accepts filesystem paths, file URLs, and any URI that git supports.

Learn more:

branches

The branches key accepts a list of branch name patterns, either as exact names or shell glob patterns (v3.*). When no branches are specified for a content repository URL, Antora will use the default branches set, i.e., the master branch and every branch that begins with v.

Learn more:

start_path

Antora automatically looks for the component descriptor file at the root of a repository. When the documentation component isn’t stored at the root, you need to specify the repository relative path to the component descriptor’s location using start_path.

Learn more:

UI keys

The ui category contains keys that specify the location of the UI bundle and how it should be processed.

bundle

The URL or local filesystem path of the UI bundle. Filesystem paths can be absolute or relative to the location of the playbook file.

Learn more:

start_path

The path inside the bundle from which UI files should be selected. Defaults to the root of the bundle.

Learn more:

default_layout

The default layout key applies a layout template to pages that don’t specify a page layout.

Learn more:

output_dir

The output directory path where the UI files are written in the published site. When the UI output_dir isn’t specified, the files are published to the _ directory relative to the root of the published site.

Learn more:

Output keys

The output category contains common output settings and a list of destination specifications. The destination specifications tell Antora which provider(s) to use to publish the site (e.g., fs, archive, ssh, s3) and where those files should go. The provider, in turn, determines which transport protocol to use (local, SSH, HTTP, etc.) and manages the low-level details of publication.

The output key is not required.

clean

The clean key is a boolean. By default, it’s set to false (turned off). When true (turned on), it will remove the destination path recursively before generating the site. This key only applies to the filesystem providers currently.

Use this key with great care. For example, if you set dir to your computer’s home directory and clean to true, you will delete ALL of the folders and files in your home directory.

dir

The output dir key specifies the directory to publish the generated site files. The key accepts a relative or absolute filesystem path. When the value is a relative path, the path is resolved relative to the playbook file.

If the destinations are unspecified, and the dir key is not set, the value defaults to build/site.

The dir key overrides the path key of the first fs provider in the list of destinations. This allows the output directory to be overridden from the CLI using the --to-dir=<dir> option.

Learn more:

destinations

The destinations key contains a list of specifications that determine how, by which provider, and where the site will be published. A site can be published to multiple destinations.

When no destinations are specified, Antora publishes the site to the local filesystem at the location specified by the dir key or, if the dir key is not specified, the default output directory location (build/site).

To disable publishing entirely, including the default output, set destinations to an empty array ([]).

provider

The provider key specifies the transport protocol Antora should use for publishing the generated site. Antora has two built-in providers, fs (filesytem) and archive (ZIP archive). This value is also an extension point that can be used to delegate to a custom provider, such as SSH, S3, etc. The default provider is fs.

Learn more:

path

The path key designates the target location where the output file(s) are to be written. The value gets interpreted appropriately by each provider. For example, the fs provider treats this value as a target directory, while the archive provider treats it as the target file.

If the path key is not specified, it typically gets populated with a default value. The default fs path is build/site, and the default archive path is build/site.zip. The key accepts a relative or absolute filesystem path. A relative path is resolved relative to the playbook file.

If you set the dir key in the playbook or via the CLI, its value will override the path value for the first fs provider specified in the destinations key.

Learn more:

clean

The clean key can be specified directly on any fs provider. When specified at this location (instead of directly under output), it only cleans the output location specified by this destination.