Content Keys

The playbook keys configured under content and sources define the locations of the content source repositories and how they’re processed.

content key

The content sources git references and other source location properties are defined under the required content key. The branches, tags, and edit_url keys can be specified directly on content. They can also be listed under sources or under both content and sources in a playbook.

content: (1)
  branches: [v2.0, v2.5, v3.0] (2)
  tags: [release/*, '!release/*-patch'] (3)
  edit_url: '{web_url}/blob/{refname}/{path}' (4)
  sources: (5)
  - url: https://git-service.com/org/repo-z.git (6)
    start_path: path-to/content-source-root (7)
  - url: https://git-service.com/org/repo-y.git (8)
1 Required content key
2 Optional branches key
3 Optional tags key
4 Optional edit_url key
5 Required sources key
6 Required url key
7 Optional start_path key
8 Another url key

The content and sources keys are required. The sources key must contain at least one entry with the url key defined. All other keys are optional. The branches and edit_url keys have built-in values Antora automatically applies at runtime if they’re not explicitly set in the playbook.

Keys-value pairs that are specified directly under content are applied to all of the url key entries under sources, unless the key is also specified on a specific url.

sources key

The sources key is required and nested under the content key. The sources key contains a list of source entries, which consist of a git repository location, branch and/or tag name patterns, and other repository properties that Antora uses when aggregating the site content. The sources key must contain at least one entry with a url key defined.

content: (1)
  sources: (2)
  - url: https://git-service.com/org/repo-z.git (3)
    branches: [v1.*, v2.*, !v1.2] (4)
    start_paths: path-to/content-source-root-{item..item} (5)
  - url: https://git-service.com/org/repo-y.git (6)
    branches: [] (7)
    tags: [release/*, '!release/*-patch'] (8)
    start_path: path-to/content-source-root (9)
    edit_url: '{web_url}/blob/{refname}/{path}' (10)
1 Required content key
2 Required sources key
3 Required url key
4 Optional branches key
5 Optional start_paths key
6 Another url key
7 Optional branches key
8 Optional tags key
9 Optional start_path key
10 Optional edit_url key

The content and sources keys are required. The sources key must contain at least one entry with the url key defined. All other keys are optional. The branches and edit_url keys have built-in values Antora automatically applies at runtime if they’re not explicitly defined in the playbook.

Available content keys

The following keys can be defined under the content key. With the exception of the sources key, which contains the source entries themselves, these keys are used to provide default values for each source entry.

Content Keys Description Required

branches

Accepts a list of branch names or glob patterns to use from the repository specified in the content source.

No

edit_url

Accepts a URL pattern for building the URL that maps to the source view for the current page. Accomodates the following placeholder segments: {web_url}, {refname}, and {path}.

No

tags

Accepts a list of tag names or glob patterns to use from the repository specified in the content source.

No

sources

Accepts a list of content source entries that specify which repositories and repository references to use as content.

Yes

Available content source keys

Content Keys Description Required

branches

Accepts a list of branch names or glob patterns to use from the repository specified in the content source. If not specified, defaults to the value of the branches key defined on the content key.

No

edit_url

Accepts a URL pattern for building the URL that maps to the source view for the current page. Accomodates the following placeholder segments: {web_url}, {refname}, and {path}.

No

start_path

Specifies the relative path in the repository to a content source root’s location.

No

start_paths

Accepts a list of repository relative path patterns to content source root locations, either as exact paths or shell glob patterns. Single values are coerced into an array.

No

tags

Accepts a list of tag names or glob patterns to use from the repository specified in the content source.

No

url

Accepts the URL of a git repository, which can either be an HTTPS URL or a local filesystem path.

Yes