On this page, you’ll learn:
How to configure the content source URL key.
How to configure the branches key.
How to configure the tags key.
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 sources URL key (
url) 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 any URI that git supports, including a local filesystem path.
Antora permits the value of
url to be a relative or absolute filesystem path.
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 (starting from the directory of the playbook)|
A relative path is expanded to an absolute path using the following rules:
If the first path segment is a tilde (
~), the path is resolved relative to the user’s home directory.
If the first path segment is a dot (
.), the path is resolved relative to the location of the playbook file.
If the first path segment is tilde plus (
~+), or does not begin with an aforementioned prefix, the path is resolved relative to the current working directory.
Like with git, Antora differentiates between a local filesystem path and a remote URI based on certain characters in the value. Consider the following two rules:
The value contains a colon that’s not followed by a forward slash or backslash (e.g.,
The value contains a colon that’s followed by two forward slashes (i.e.,
If the value matches either of these rules, the value is handled as a remote URI, not a local filesystem path.
Note that a colon is permitted when it’s part of a Windows drive letter (e.g.,
Look for these rules in the sections that follow.
|In order to use a local content repository with Antora, even when using the worktree (i.e., HEAD), the repository must have at least one commit. If you’re not ready to commit other files, simply create an empty .gitignore file and commit it.|
When using a local, non-bare repository, Antora reads files from the worktree (i.e., the working directory) when the current branch is matched by the branches filter.
(You can use the value
HEAD in the branches filter as a shorthand for the current branch).
content: sources: - url: ./demo-component-b branches: HEAD, some-other-branch
This behavior is central to author mode. It means you don’t have to commit files locally for Antora to use them.
|If the current branch is matched by the branches filter, and the worktree contains the same files with the same component version as another branch matched by the branches filter, Antora will fail to run because it disallows duplicate files.|
To ensure Antora doesn’t use files from the worktree for a local URL, change the URL to point directly to the .git directory. That way, the worktree is out of Antora’s purview.
content: sources: - url: ./demo-component-b/.git
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: email@example.com:antora/demo/demo-component-b.git - url: git://github.com/org/content-repo.git - url: https://%GITHUB_TOKEN%:firstname.lastname@example.org:org-name/project-docs.git
Whether or not the
.git extension is required depends on the settings of the git host.
It’s usually best to include it.
See Private repository authentication to learn how to use Antora to connect to private repositories over HTTP/HTTPS using a username+password or OAuth token.
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.
These patterns are case insensitive (i.e., the characters are matched regardless of case).
Let’s look at some examples of each of these name declaration methods.
When no branches are specified for a source, Antora will use the default branch filter. By default, Antora will select branches from the repository that begin with “v” as well as the branch named “master”.
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, simply assign a value to the
branches key directly on 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
branches as long as the values are inside a set of square brackets (
) per YAML rules.
If there is only one branches value, it doesn’t need to be enclosed in square brackets (
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: [v1.0, v2.0] (1) - url: https://gitlab.com/antora/demo/demo-component-a.git branches: master (2)
|1||Comma-separated branches values|
|2||A single branches value doesn’t need to be enclosed in square brackets|
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-b.git branches: - v1.* (1) - v2.0.0 - v2.1.*
|1||Marker-separated branches values|
Branches can be specified by their exact name.
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.git branches: - issue-27-sneaky-chinchilla - master - '1.0' - v2.0
A branch name that begins with a number, like
1.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 B except for
You’d enter the following branches values into the playbook:
content: sources: - url: https://gitlab.com/antora/demo/demo-component-b.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-b.git branches: - v* - '!v*-beta'
The tags key (
tags) accepts match patterns just like the branches key.
Tags are not used by default.
If you want to apply the same tag filter to all source entries that don’t declare the
tags key explicitly (i.e., a default tag filter), assign a value to the
tags key directly on the
content: tags: v* sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
Antora will now discover and use tags that begin with “v” for all content sources that don’t declare the
In this example, we’ll fetch the “master” branch from a content repository. From the same repository, we’ll also fetch all of the tags starting with “v”.
content: sources: - url: https://gitlab.com/org/project-docs.git branches: master tags: v*
If you only want to use tags, you must explicitly disable branches.
content: sources: - url: https://gitlab.com/org/project-docs.git branches: ~ tags: v*
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 B’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-b.git branches: [v1.*, v2.*] - url: ./docs-site/demo-component-b 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.