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, sources, and url keys are required. The 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 the list of git repository locations, 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 url key with an assigned value.

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, sources, and url keys are required. The 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

Content Keys Description Required

branches

Accepts a list of branch name patterns, either as exact names or shell glob patterns.

No

edit_url

Accepts a URL pattern that contains the URL segments of the git solution or source file view plus three placeholder segments, {web_url}, {refname}, and {path}.

No

sources[n].url

Accepts any URI that git supports, including a local filesystem path.

Yes

sources[n].start_path

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

No

sources[n].start_paths

Accepts a list of repository relative path patterns to content source root locations, either as exact paths or shell glob patterns.

No

tags

Accepts a list of tag name patterns, either as exact names or shell glob patterns.

No