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 is 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 CSON.

YAML is a common configuration language for defining automated tasks. Most of the playbook examples in this documentation use YAML since it’s less verbose than JSON and CSON.

Regardless of the format, a playbook contains structured categories and keys for specifying general site properties, content and UI input sources, and published output destinations and providers.

What’s next?