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 a factitious example of a playbook file showing all the keys that can be defined.

This example is meant for illustration and is not intended to be copied.
site: (1)
  title: Demo Docs Site (2)
  url: https://demo.antora.org (3)
  start_page: component-b::index.adoc (4)
  keys: (5)
    google_analytics: XX-123456 (6)
content: (7)
  sources: (8)
  - url: https://gitlab.com/antora/demo/demo-component-b.git (9)
    branches: [v1.0, v2.0] (10)
    tags: v3.* (11)
    start_path: docs (12)
asciidoc: (13)
  attributes: (14)
    linkattrs: ''
    toc: ~
ui: (15)
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable (16)
    snapshot: true
    start_path: dark (17)
  default_layout: base (18)
  output_dir: _/dark (19)
output: (20)
  clean: true (21)
  dir: ./public (22)
  destinations: (23)
  - provider: archive (24)
runtime: (25)
  cache_dir: ./.cache/antora (26)
  pull: true (27)

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

Site category

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 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 global site services such as document search tools and Google Analytics.

google_analytics

This key associates a Google Analytics account with the site.

Learn more:

Content category

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

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 any URI that git supports, including a local filesystem path.

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 sources url, Antora will use the default branches set, i.e., the master branch and every branch that begins with v.

Learn more:

tags

The tags key (tags) accepts a list of tag name patterns, either as exact names or shell glob patterns.

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:

AsciiDoc category

The asciidoc category contains keys that configure the AsciiDoc processor, such as AsciiDoc document attributes and extensions.

attributes

The attributes key under the asciidoc category is a map used to define global (i.e., site-wide) AsciiDoc document attributes. These document attributes are made available to each page in the site.

Learn more:

extensions

The extensions key under the asciidoc category is an array used to specify a set of Asciidoctor extensions to register. Each entry is either the name of an installed module or the path to a local script. Depending on the capabilities of the extension, the extension will either be registered globally or be scoped to the AsciiDoc processor instance for a page.

Learn more:

UI category

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

url

The url key under the bundle subcategory accepts a URL or local filesystem path to a UI bundle ZIP archive. The filesystem path can be absolute or relative.

Learn more:

snapshot

The snapshot key under the bundle subcategory indicates whether the URL points to a snapshot (i.e., it doesn’t always point to the same artifact). By default, Antora assumes that URL is permanent.

Learn more:

start_path

The start_path key under the bundle category is the path inside the bundle from which UI files should be selected. When no value is specified, it 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

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

Learn more:

Output category

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.

If the destinations are unspecified, and dir 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.

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.

Runtime category

The runtime category contains keys that manage the console output, resource update behavior, and cache location.

cache_dir

The cache_dir key specifies the directory where Antora will cache any remote git repositories and UI bundles. The key accepts a relative or absolute filesystem path. If cache_dir isn’t set, the repositories and UI bundle are saved to the antora folder under the operating system cache directory for the current user.

Learn more:

pull

If you want Antora to refresh the files in the cache, you need to set the pull key under the runtime category to true.

Learn more: