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 contrived example of a playbook file showing all the keys that can be defined.
| Do not copy and paste this listing! It’s only meant to serve as a reference to illustrate all the available keys and possible values in a playbook. If you try to use it as is, it will not work. Use the demo site.yml instead if you’re looking for a starting point. |
site: (1)
title: Docs Site (2)
url: https://docs.example.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: ~
extensions:
- ./lib/custom-block.js
ui: (15)
bundle:
url: https://example.org/docs-ui/download/latest/ui-bundle.zip (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)
fetch: 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.
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:
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 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 (filesystem) 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:
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: