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

branches

Accepts a list of exact branch names and name 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. Accommodates the following placeholder segments: {web_url}, {refname}, {refhash}, and {path}.

No

sources

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

Yes

tags

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

branches

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 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. Accommodates the following placeholder segments: {web_url}, {refname}, {refhash}, 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 exact tag names and name 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

version

Provides a fallback value for the version key in the component version descriptor for all references matched.

No

worktrees

Accepts a keyword or list of exact branch names or name patterns to control which corresponding worktrees Antora should use.

No