Content Configuration

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 content and sources categories in the playbook schema. These keys define the location of the documentation component repositories (url and start_path) and control which branches (branches) should be processed.

URL key

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.

Use local content repositories

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

Local git repositories
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., host:repo).

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

Fetch remote content repositories

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

Remote git repositories
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: git@gitlab.com: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.

Configure local and remote URLs in the same playbook

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

Branches key

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.

Default branch filter

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

Use default branch filter
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 category.

Modifying the default branch filter
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 branches key.

Separate branches values using commas or markers

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

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

Specify branches by name

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.

Using the current branch

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.

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.

Specify branches by glob pattern

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:

Glob branch patterns
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 -beta.

Exclude branches ending in -beta
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches:
    - v*
    - '!v*-beta'

Tags key

The tags key (tags) accepts match patterns just like the branches key.

Setting the tags key does not disable the default branches. If you want to disable all branches, you must set the branches key to an empty array (e.g., []).

Add a default sources tag filter

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.

Assign a default tag filter to content sources
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 tags key.

Use tags and branches from the same content repository

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*

Mix local and remote repositories and 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.

Use remote and local repositories and branches
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

Start path key

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.

Specify a start path

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.

Start path directory

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.

Set start_path
content:
  sources:
  - url: https://github.com/org/repo
    branches: [master, v2.6]
    start_path: packages/docs

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