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 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)
- url: https://git-service.com/org/repo-x.git (11)
branches: v* (12)
version: true (13)| 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 |
| 11 | Another url key |
| 12 | Optional branches key |
| 13 | Optional version 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.
The version key provides a fallback value for the version key in the component version descriptor (antora.yml).
You should only use it if you’re matching a single reference or you want the value to be derived from the refname.
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 |
|---|---|---|
Accepts a list of exact branch names and name patterns to use from the repository specified in the content source. |
No |
|
Accepts a URL pattern for building the URL that maps to the source view for the current page.
Accommodates the following placeholder segments: |
No |
|
Accepts a list of content source entries that specify which repositories and repository references to use as content. |
Yes |
|
Accepts a list of exact tag names and name patterns to use from the repository specified in the content source. |
No |
Available content source keys
| Content Keys | Description | Required |
|---|---|---|
Accepts a list of exact branch names and name patterns to use from the repository specified in the content source.
If not specified, defaults to the value of the |
No |
|
Accepts a URL pattern for building the URL that maps to the source view for the current page.
Accommodates the following placeholder segments: |
No |
|
Specifies the relative path in the repository to a content source root’s location. |
No |
|
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 |
|
Accepts a list of exact tag names and name patterns to use from the repository specified in the content source. |
No |
|
Accepts the URL of a git repository, which can either be an HTTPS URL or a local filesystem path. |
Yes |
|
Provides a fallback value for the |
No |
|
Accepts a keyword or list of exact branch names or name patterns to control which corresponding worktrees Antora should use. |
No |