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.
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)
|3||Base URL key|
|4||Start page key|
|6||Google analytics key|
|9||Content repository URL key|
|10||Content repository branches key|
|11||Content repository start path key|
|13||UI bundle repository key|
|14||Bundle start path key|
|15||UI default layout key|
|16||UI output directory key|
|17||Published output keys|
|18||Clean output directory key|
|19||Output directory key|
|20||Output destinations key|
|21||Output provider key|
Let’s explore the purpose and usage of each key and its values.
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.
The title of the documentation site.
The url key is the base URL of the published site.
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.
The account keys for site-wide services such document search tools and Google Analytics.
The google_analytics key associates a Google Analytics account with the site.
content category contains an array of source repository specifications.
These source repository specifications are arranged under the
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.
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.
The branches key accepts a list of branch name patterns, either as exact names or shell glob patterns (
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
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
ui category contains keys that specify the location of the UI bundle and how it should be processed.
The URL or local filesystem path of the UI bundle. Filesystem paths can be absolute or relative to the location of the playbook file.
The path inside the bundle from which UI files should be selected. Defaults to the root of the bundle.
The default layout key applies a layout template to pages that don’t specify a page layout.
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.
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.
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
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
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 (
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
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.
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