Playbook

Antora separates the content (kept in the repositories of each product), the presentation (the UI bundle) and the assembly instructions. The playbook holds the assembly instructions, so one team can build the same content with different settings, for example a production build with site.url set and a local build without it, without touching a single content repository. A playbook is a file, but most of its keys can also be overridden per run from the command line or from environment variables, which is how continuous integration jobs adjust a shared file.

The file can be written in YAML, JSON or TOML. YAML is by far the most common format and is used in this page. The file name is yours to choose; this site and the Pocket Units example use antora-playbook.yml. When the name given to the generator has no extension, the playbook builder tries the extensions .yml, .json and .toml in that order. A relative path in a playbook value resolves from the current working directory by default; prefixing it with ./ resolves it from the directory of the playbook file instead, which makes the playbook portable between machines.

The playbook is passed to the generator on the command line:

Source: Antora docs: Antora CLI

Antora validates the playbook against a schema before doing any work. An unknown key is an error, so a typo is caught immediately. This was checked with a playbook containing site.titel:

A value of the wrong type or outside the allowed choices is reported with the key path and the file it came from:

The only key that must always be provided is the UI bundle URL (ui.bundle.url). A playbook without it fails with ui.bundle.url: must be of type String. A site also needs at least one entry in content.sources to have pages.

The running example, Pocket Units, is a tiny units-conversion library documented from two release branches (v1.0 and v2.0) of one repository plus a shared component. The playbook below sets one key from each group. It was built with Antora 3.2.1 against local repositories and the Antora Default UI built from source; the build finished with exit code 0.

Source: Antora docs: Playbook

The result is a public folder with the component versions published under pocket-units/1.0 and pocket-units/current, a robots.txt containing Allow: /, one sitemap per component and an index.html that redirects to the start page. The start page redirect points at pocket-units/current/, which shows the effect of latest_version_segment on the newest version.

Two keys sit outside the groups below and are normally left alone.

Source: Antora docs: Antora keys

The extension options shown (index_latest_only) belong to the extension, not to Antora. This snippet was not executed as shown because the Lunr extension was installed in the scratch project but not exercised.

The site keys describe the site as a whole.

Source: Antora docs: Site keys

A few details are worth knowing. Without site.url there is no sitemap and the siteMapped generator event does not fire; a site built that way is intended for local preview. The environment variable for the Google Analytics key is GOOGLE_ANALYTICS_KEY, and it fills site.keys.google_analytics, so the account key can stay out of the file. Environment variables are named URL for the site URL, which is easy to clobber in a shell that already defines it.

The effect of the 3.2 trailing-slash normalisation was checked by passing a URL that ends in a slash:

Here show.js is a throwaway script calling @antora/playbook-builder and printing parts of the resulting playbook.

The content keys list where the documentation comes from. They are covered key by key in Content sources; this section only lists them so the playbook reference is complete.

Source: Antora docs: Content keys

A source that sets its own branches replaces the default for that source only, as ./shared does in the Pocket Units playbook above. Antora 3.2 added git.fetch_depth, linked worktrees, submodules, HEAD@<worktree> and a commits filter; the commits filter is part of the playbook model but cannot be written in a playbook file.

The ui keys select and adjust the UI bundle, the ZIP archive with the page templates, CSS and JavaScript.

Source: Antora docs: UI keys

A remote bundle is cached by URL. That is why snapshot: true matters for a bundle published under a fixed URL. This site also sets the key, but its ui.bundle.url is the local path ui-bundle.zip, which Antora reads on every build, so snapshot has no effect here; it only matters for remote URLs. Supplemental files are used here to ship .nojekyll, which stops GitHub Pages from dropping the _ folder. The UI bundle itself is covered in the UI bundle subsection.

Source: Antora docs: Supplemental UI

Supplemental files are given either as a directory or as a list, never both. A file at the same path as a file in the bundle overrides it, and a supplemental ui.yml replaces the one in the bundle. This example mirrors what this site does and was not built separately.

The asciidoc keys control the conversion of every page.

Source: Antora docs: AsciiDoc keys

Attributes defined here sit at the bottom of a precedence order that the descriptor of each component, and finally the page header, can override; the full order is explained in AsciiDoc attributes and extensions. Since Antora 3.2, values are no longer stripped of their quotes and a value is only parsed as YAML when it carries a YAML tag, so write plain scalars when in doubt.

The urls keys shape the addresses of pages.

Source: Antora docs: URLs keys

In the Pocket Units build, html_extension_style: indexify produced addresses such as pocket-units/current/getting-started/index.html, linked as pocket-units/current/getting-started/. This is the style GitHub Pages and most static hosts serve cleanly. Antora 3.2 also changed output paths and URLs so they follow the versionSegment of the component version, covered in Versioning and prerelease. The redirect facilities other than static produce redirect rules for the named server instead of HTML pages.

The output keys say where the site goes.

Source: Antora docs: Output keys

The providers are fs, which writes files, and archive, which writes a ZIP. A site was published to both with this fragment, and the run finished with exit code 0:

Source: Antora docs: Output keys

Listing the archive contents afterwards printed entries such as pocket-units/current/changelog/index.html. Setting destinations: [] disables publishing, which is useful when an extension handles delivery itself.

The runtime keys control how the generator behaves while it runs.

Source: Antora docs: Runtime keys

The fetch key explains the repository rule: a plain npx antora antora-playbook.yml only reads what is already in the cache, and npx antora --fetch antora-playbook.yml first pulls the latest branches of the remote sources. That matters when the cache persists between builds; this site’s nightly workflow runs npx antora antora-playbook.yml on a fresh runner whose cache starts empty, so every remote source is cloned anyway. failure_level is the key to adopt in a continuous integration job. Setting it to warn makes a broken cross-reference fail the build, and since Antora 3.2 the process then exits with code 2 rather than 1.

The stack trace option is a global option of the antora command, written before the command name:

Source: Antora docs: Antora CLI

This command line was not run as such; the options individually were exercised with a throwaway script and a full build.

The git keys tune the built-in Git client.

Source: Antora docs: Git keys

The default fetch_depth of 1 limits how much history is downloaded from remote repositories; use a larger value, or 0 for the full history, when you need more commits. Private repositories are authenticated over HTTPS through a credentials file or the GIT_CREDENTIALS variable; SSH keys are not supported and SSH URLs are converted to HTTPS. Never write a real token into a playbook. Keep the value in a CI secret:

Source: Antora docs: Private repository authentication

This example was not executed because it needs a private remote repository and a real token.

The network keys configure a proxy for the Git client and for downloading the UI bundle.

Source: Antora docs: Network keys

The proxy variables use the lower-case names common to other tools. These keys were checked against the schema; no proxy was available to test them.

Each value comes from the first source that defines it, in this order, highest priority first:

The order was tested by loading the Pocket Units playbook, which sets a title, a URL, a log level of info and an attribute version-label, with progressively more overrides. With no overrides the values come from the file:

The environment variables URL=https://env.example.org and ANTORA_LOG_LEVEL=debug replace the URL and the level:

Adding CLI options on top of the same environment (--url https://cli.example.org --title "CLI title" --attribute version-label=cli --attribute extra=1 --log-level error --fetch --to-dir out --html-url-extension-style indexify) replaced everything that was set on the command line, including the log level that the environment had changed:

Two details from the output matter. Attributes passed with --attribute are merged key by key into the attributes of the file: version-label was replaced, and a new key extra was added, while keys that the command line did not mention stay. Repeatable options such as --attribute, --key and --extension collect all the occurrences.

Not every key can be overridden. The table lists what the command line and the environment can set, taken from the schema of 3.2.1.

Source: Antora docs: Playbook

All environment variables supported by the schema are collected here.

Source: Antora docs: Playbook

No variable names the playbook file itself; it is chosen only by the command argument. The table of overridable keys is derived from the schema shipped with @antora/playbook-builder 3.2.1 and reflects that version.