The Antora Playbook

On this page, you’ll learn:

  • The purpose of an Antora playbook.

  • Where the playbook file is located.

  • The playbook file formats Antora accepts.

What’s an Antora playbook?

An Antora playbook makes it easy for technical writers to control what content is included in your site, what user interface (UI) is applied to it, and where the site is published using a playbook file. The settings in the playbook file, in combination with CLI options and environment variables, tell Antora how to operate.

Specifically, a playbook tells Antora:

Additionally, certain settings in the playbook file can be overridden using CLI options or environment variables, which allows an operations team to tailor the behavior for specific environments, such as production.

Where is a playbook stored?

A playbook is usually located in a playbook project. A playbook project repository is responsible for generating a documentation site. It’s strictly a configuration as code repository—​it does not contain any content. Instead, it contains a playbook file, and, in certain situations, supplemental UI files and extension code.

Playbook file formats

Playbooks can be written in YAML, JSON, and TOML. YAML is a common configuration language for defining automated tasks and most of the playbook examples in this documentation use YAML. But you’re free to use any of these formats.

Regardless of its format, a playbook contains structured key-value pairs for specifying general site properties, content and UI input sources, and published output destinations and providers.

Relative paths in a playbook

By default, Antora resolves relative paths in the playbook from the current working directory. For example, the path public is effectively $PWD/public. If, instead, you want Antora to resolve relative paths from the directory where the playbook file is located, prepend ./ to the path (e.g., ./public).

By starting relative paths with ./, you make your playbook more portable. It means you can run the antora command from any directory on the filesystem and the behavior will be the same.

If you don’t start relative paths with ./, the path Antora resolves is dependent on the current working directory. To get portable behavior, you have to switch to the directory where the playbook file is located before running the antora command.

Only use bare relative paths if you intend the path to be tied to the current working directory.