Set Up a Playbook

Let’s create a basic playbook file in the YAML format. The steps in the following sections will walk you through setting up a playbook that configures a site title and URL, fetches source files from the Demo Component A and Demo Component B repositories, and applies Antora’s reference UI to the converted pages.

Configure your site’s properties

First, let’s configure your site’s title and URL.

Open a new file in the text editor or IDE of your choice. You’ll typically name this file antora-playbook.yml.
On the first line, type site: and press Enter to go to the next line.
site:
The site key accepts a map of key-value pairs that define global site properties.
The title key is a child of site. Type title: and then the text that will become the title of your site. Press Enter.
```
site:
  title: My Demo Site
```
Type url: and then the base URL of your site.
site: title: My Demo Site url: https://docs.demo.com
Assigning an absolute URL to the url key activates secondary features such as the sitemap.
On the next line, enter start_page: and the page ID of the page Antora should use as the site’s home page.
site: title: My Demo Site url: https://docs.demo.com start_page: component-b::index.adoc
The start_page value in the example above is the page ID for the latest version of the file index.adoc that belongs to Component B. In order for Antora to use this page, you need to tell Antora where to find the source files that belong to Component B.

In the next section, let’s define the content sources URLs, branches, and start paths.

Configure your site’s content sources

Antora needs to know what git repositories, branches, and tags it should locate and fetch source files from, as well as the location of any content source roots that aren’t at the root of a repository. Let’s define these keys in the playbook file you started in the previous section.

Type content: flush against the left side of the file. Press Enter to go to the next line.
```
# ...
  start_page: component-b::index.adoc
content:
```
The sources key is a child of content. Type sources: and press Enter.
# ... start_page: component-b::index.adoc content: sources:
The sources key requires at least one url key be assigned a remote repository URL or filesystem path. Let’s assign the URL for a remote repository named Demo Component A to url in the next step.
Type a hyphen (-) followed by a blank space. Then type url: and the URL of a content source repository.
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git
Now, Antora can locate the Demo Component A repository. But it also needs to know what branches and tags it should fetch.

The default branches filter is applied at runtime when a url key doesn’t have a branches or tags key set on it. Since the Demo Component A repository only has one branch, and that branch’s name (main) falls within the parameters of the default filter, you don’t need to explicitly set branches on this url key.
Let’s add the URL for the Demo Component B repository. On a new line, type - url: and the repository’s URL.
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
The Demo Component B repository uses branches for versioning. The content source files in the branches v1.0 and v2.0 are ready for publishing. However, you can’t use the default branches filter on this url because the files in the main branch shouldn’t be published to the site. Instead, you’ll have to tell Antora what branches it should fetch from the Demo Component B repository.

On the next line, type branches: and an opening square bracket ([). Inside the [, type each branch name that Antora should fetch. Separate the values with commas. It doesn’t matter what order you list the branch names. At the end of the list, type a closing square bracket (]). Press Enter.

# ...
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]

Make sure to indent branches enough so the u in url and b in branches are lined up.

The branches key also accepts shell glob patterns. For instance, you could define branches: v* on the url key for Demo Component B to specify that Antora fetch the branches with the names v1.0 and v2.0.

You’re not done configuring the keys for the Demo Component B repository just yet. The content source root in each branch isn’t at the root of the repository, it’s at docs. You’ll need to set the start_path key on url so Antora can locate the content source root.

Type start_path: and the repository root relative path.

# ...
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs

Don’t add leading or trailing slashes to the path.

Now, you’re ready to configure the final set of required keys that will tell Antora what UI it should apply to the site.

Configure your site’s UI bundle

Antora needs a UI bundle in order to generate a site. Let’s tell Antora to use it’s reference UI bundle by defining the required keys in the playbook file you worked on in the previous sections.

Flush against the left side of the file, type ui:. Press Enter to go to the next line.
```
# ...
    start_path: docs
ui:
```
The bundle key is a child of ui. Type bundle: and press Enter.
```
# ...
    start_path: docs
ui:
  bundle:
```
The url key is a child of bundle. Type url: and then the URL of Antora’s reference UI bundle.
# ... start_path: docs ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
Antora’s reference UI archive changes over time, but its URL doesn’t, so you need to activate the snapshot key.

On the next line, enter snapshot: and the value true.

# ...
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

When snapshot is set to true, Antora will download the UI bundle whenever fetch is activated in the playbook or from the CLI.

You’re almost done! Here’s the entire playbook file you’ve assembled so far.

site:
  title: My Demo Site
  url: https://docs.demo.com
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

This playbook will generate a site named My Demo Site using the content files from the specified repository branches and the UI files from the specified UI bundle.

All you’ve got to do before running Antora on this playbook is save it. Playbook files are often saved with the filename antora-playbook.yml or a related filename, such as local-antora-playbook.yml, depending on the context in which it’s used.

Once you’ve saved the playbook file, you’re ready to run Antora.

You can also get this playbook from the Demo Docs Site repository.

Using self-signed certificates

When using either a secure (HTTPS) content source URL or a secure (HTTPS) UI bundle URL that has a self-signed certificate, additional configuration is required. By default, Node.js will refuse to make a TLS connection (i.e., HTTPS) and report one of the following errors:

FATAL (antora): self-signed certificate
FATAL (antora): Failed to download UI bundle

Underneath the covers, Antora uses Node.js’ https module for both git operations and the UI download. When connecting to a secure URL that has a self-signed certificate, Node.js requires additional configuration to recognize and accept that certificate. This configuration extends to extensions that use the Node.js https module as well.

There are several environment variables you can use to configure Node.js to recognize and accept self-signed certificates.

NODE_TLS_REJECT_UNAUTHORIZED=0

Turns off the behavior in Node.js to check unauthorized certificates.

$ NODE_TLS_REJECT_UNAUTHORIZED=0 antora playbook.yml

NODE_USE_SYSTEM_CA=1

Configures Node.js to load system CAs in addition to its bundled CAs for TLS validation.

$ NODE_USES_SYSTEM_CA=1 antora playbook.yml

NODE_EXTRA_CA_CERTS=<path/to/>/certificates.pem

Configures additional CA certificates that Node.js should consider as authorized. Replace <path/to/> with the path prefix of the certificates file.

$ NODE_EXTRA_CA_CERTS=<path/to/>/certificates.pem antora playbook.yml

For more information about these environment variables, refer to the Node.js CLI documentation (search for "https").