Content Configuration

Antora permits the value of url to be a relative or absolute filesystem path.

A relative path is expanded to an absolute path using the following rules:

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:

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., c:/). Look for these rules in the sections that follow.

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).

This behavior is central to author mode. It means you don’t have to commit files locally for Antora to use them.

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.

Remote repositories can be fetched via URLs (http, https), SSH URIs, and git URIs.

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.

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.

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 category.

The new default branch filter will be applied to all entries that do not themselves have a value defined for the branches key.

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 (branches: v1.0).

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.

Branches can be specified by their exact name.

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, 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 v3.4.*. 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 1.7. You’d enter the following branches values into the playbook:

A negated value must be enclosed in single quotes, per YAML rules.

Here’s how you’d exclude all branches that end in -beta.

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 category.

Antora will now discover and use tags that begin with “v” for all content sources that don’t declare the tags key.

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.

If you only want to use tags, you must explicitly disable branches.

You can generate your site using remote branches and a local branch of a component. In this example, we’ll fetch all of the v1.x and v2.x branches from Component B’s remote content repository. We’ll also load the branch v3.0.0-beta from a local repository.

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.

With start_path specified, Antora won’t collect any files outside of https://github.com/org/repo/packages/docs.