Content Configuration

On this page, you’ll learn:

  • How to configure the content source URL key.

    • Relative and absolute filesystem paths

    • Git URIs

  • How to configure the branches key.

    • By name

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

Use local content repositories

The url accepts a relative or absolute filesystem path. When the value is a relative path, the path is resolved relative to the playbook file.

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

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.

Let’s look at some examples of each of these name declaration methods.

Default branch filter

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

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, then assign a value to the branches key directly under 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 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

Specify branches by name

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.

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.*. 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 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-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 -beta.

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

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 A’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-a.git
    branches: v1.*, v2.*
  - url: docs-site/demo-component-a
    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.