On this page, you’ll learn:
How to configure the content source URL key.
Relative and absolute filesystem paths
How to configure the branches key.
By glob pattern
How to mix local and remote repositories and branches.
When and how to configure the start path key.
The keys documented on this page are organized under the
sources categories in the playbook schema.
These keys define the location of the documentation component repositories (
start_path) and control which branches (
branches) should be processed.
The url key tells Antora where to find a documentation component’s repository. You must provide a value for each documentation component repository you want added to your site. The key accepts filesystem paths, file URLs, and any URI that git supports.
url accepts a relative or absolute filesystem path.
When the value is a relative path, the path is resolved relative to the playbook file.
content: sources: - url: /home/user/docs-site/demo-component-a (1) - url: demo-component-b (2)
|1||Absolute path to git repository|
|2||Relative path to git repository|
Remote repositories can be fetched via URLs (http, https), SSH URIs, and git URIs.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: firstname.lastname@example.org:antora/demo/demo-component-b.git - url: git://github.com/org/content-repo.git
Whether or not the
.git extension is required depends on the settings of the git host.
It’s usually best to include it.
You can build your documentation site using a combination of local and remote content repositories, even when the local repositories have uncommitted changes.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: demo-component-b
The branches key accepts a list of branch name patterns.
The names can be specified in a comma-separated list or as single items on individual lines.
The values can be the exact name of a branch, a shell glob pattern such as
v3.*, or a combination of exact and glob names.
Let’s look at some examples of each of these name declaration methods.
When no branches are specified for a source URL, Antora will use the default branches set.
Antora assumes that a repository’s default branches set is the
master branch and every branch that begins with
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
The result of the example above is the same as if you specified the master branch and all of the version branches explicitly,
branches: master, v*.
If you want to modify the default branch filter, then assign a value to the
branches key directly under the
content: branches: v* sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
The new default branch filter will be applied to all entries that do not themselves have a value defined for the
Branch names can be separated by commas (
,) and listed on the same line as the branches key.
Alternatively, each branch name can be specified on its own line, using a hyphen (
-) list marker (per YAML rules), and listed beneath the branches key.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git branches: master, v1.* (1) - url: https://gitlab.com/antora/demo/demo-component-a.git branches: - v1.* (2) - v2.0.0 - v2.1.*
|1||Comma-separated branches values|
|2||Marker-separated branches values|
Branches can be specified by their exact name.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git branches: - master - '1.0.0' - v2.0.0
A branch name that begins with a number, like
1.0.0 must be enclosed in single quotes (
'), per YAML rules.
When working with a local repository, you may find yourself switching between branches often.
To save you from having to remember to update the playbook file to point to the current branch, you can use a special keyword,
content: sources: - url: workspace/project-a branches: HEAD
Using the value
HEAD is equivalent to using the name of the current branch.
All the same rules apply.
Branches can be specified by shell glob patterns such as as
If the pattern starts with a
! character, then it is negated (i.e., the matches are excluded).
This is how you can deselect branches that were matched by a previous glob.
For example, let’s say you want to include all
1.x versions of the Component A except for
You’d enter the following branches values into the playbook:
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git branches: - v1.* - '!v1.7'
A negated value must be enclosed in single quotes, per YAML rules.
Here’s how you’d exclude all branches that end in
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git branches: - v* - '!v*-beta'
You can generate your site using remote branches and a local branch of a component.
In this example, we’ll fetch all of the
v2.x branches from Component A’s remote content repository.
We’ll also load the branch
v3.0.0-beta from a local repository.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git branches: v1.*, v2.* - url: docs-site/demo-component-a branches: v3.0.0-beta
Antora automatically looks for a component descriptor file (antora.yml) at the root of a source repository. When this default repository structure is used, the start path key doesn’t need to be set or assigned in the playbook. If the component isn’t stored at the root of a content repository, then you need to use the start path key to tell Antora where to find the component descriptor file.
The value of the start path key is the repository relative path to the component descriptor file. Let’s define the start path value for a repository with the structure shown below.
In order for Antora to locate the documentation component in this repository, the start path value needs to point Antora to the directory where antora.yml is located.
content: sources: - url: https://github.com/org/repo branches: master, v2.6 start_path: packages/docs
start_path specified, Antora won’t collect any files outside of https://github.com/org/repo/packages/docs.