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 category key encapsulates the list of content sources (i.e., git repositories) in an Antora site.
The content sources are defined using the sources key.
The branches, tags, and edit_url keys can be used to define default values for all content sources.
These keys can be redefined per content source, alongside other keys that are specific to a content source.
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.
Each entry, designated by a hyphen, consists of a git repository location (URL or filesystem path), patterns to match branches and/or tags, an optional start path or paths, and other repository properties that Antora uses when aggregating the site content.
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 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.
| If no git references (branches or tags) are matched for a content source entry, Antora will log a message at the info level. You must have the log severity level set to at least info to see this message. We recommend configuring Antora’s logger accordingly to aid with debugging. |
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 |