URLs for Content Sources

The url key tells Antora where to find a content source repository.

url key

Antora can connect to public and private git repositories that are defined be a url key in a playbook. At least one url key must be specified under the sources key. You can add as many url keys as you need. Each url key tells Antora where to find a git repository that contains content source files.

Example 1. antora-playbook.yml
content:
  sources:
  - url: https://git-service.com/org/repo.git
  - url: /absolute/path/to/local-repo

The url key accepts any URI that git supports, including a local filesystem path.

Like with git, Antora differentiates between a local filesystem path and a remote URI based on certain characters in the value. If the value matches either of the two rules listed below, the value will always be handled as a remote URI, not a local filesystem path.

  • The value contains a colon that’s not followed by a forward slash or backslash (host:repo).

  • The value contains a colon that’s followed by two forward slashes (://).

Use remote content repositories

All remote content repositories must be accessible via a URL (a web address that’s fetched using either the basic or encrypted HTTP protocol) (i.e., http:// or https://). The repository location can be expressed using a URL, an SSH URI, or a git URI. Internally, that location is always converted to a URL.

content:
  sources:
  - url: https://git-service.com/org/repo-z.git
  - url: git@git-service.com:org/repo-y.git
  - url: git://git-service.com/org/repo-x.git

Whether the .git extension is required depends on the settings of the git host. It’s not needed for repositories hosted on GitHub, required for repositories hosted on GitLab, and forbidden for repositories hosted on Team Foundation Server (TFS) or Azure DevOps, to cite a few scenarios (and to exhibit the nature of the problem). That’s why the ensure_git_suffix key is provided for you, which is enabled by default.

Antora can connect to private git repositories as long as a supported authentication method is specified for the private content source repositories.

Use local content repositories

Antora permits the value of url to be a relative or absolute filesystem path to a local repository that has at least one commit.

content:
  sources:
  - url: /absolute/path/to/local-repo (1)
  - url: https://git-service.com/org/repo-z.git
  - url: ./another-local-repo (2)
1 Absolute path to git repository
2 Relative path to git repository (starting from the directory of the playbook)
In order to use a local content repository with Antora, even when using the worktree (HEAD), the repository must have at least one commit. If you’re not ready to commit any files, you can initialize a repository and create an empty commit (e.g., git init . && git commit --allow-empty -m init).

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

  • If the first path segment is a tilde (~), the remaining path is resolved relative to the user’s home directory.

  • If the first path segment is a dot (.), the remaining path is resolved relative to the location of the playbook file.

  • If the first path segment is a tilde directly followed by a plus sign (~+), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.

Use the git worktree

When the URL for a content source is a local repository (which must have at least one commit), and the branches filter matches the branch that’s currently checked out (aka the worktree branch), Antora reads files from the worktree (i.e., the working directory on the local filesystem) instead of from the git index. This behavior is central to the author mode in Antora. It means you don’t have to commit files locally before Antora can use them.

Example 2. Use files from the worktree
content:
  sources:
  - url: ./demo-component-b
    branches: main
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

Instead of specifying the name of the current branch explicitly, you can use the symbolic name HEAD as an alias for the current branch name. This saves you the trouble of having to update your playbook when you switch branches.

Example 3. Use files from the worktree
content:
  sources:
  - url: ./demo-component-b
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0
If the branches filter matches both the worktree branch and another branch that contains the same files for the same component version, Antora will fail to run because it does not permit duplicate files.

Bypassing the git worktree

To ensure Antora doesn’t use files from the worktree, even if the branch filter matches the worktree branch, you can point the URL directly at the .git directory. This effectively hides the worktree from Antora so it won’t get used.

Example 4. Refers directly at the .git folder to bypass files in the worktree
content:
  sources:
  - url: ./demo-component-b/.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

A better way to bypass the git worktree is to set the worktrees key to false.

Example 5. Sets worktrees to false to bypass files in the worktree
content:
  sources:
  - url: ./demo-component-b
    branches: HEAD
    worktrees: false
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: v1.0, v2.0

Keep in mind that, in this case, all files must be committed locally in order for Antora to use them.