Repositories and Content Source Roots
Antora collects content source files from directories in branches, tags, and worktrees of git repositories. These source files are only retrieved and processed correctly if Antora can locate them within a content source root.
git repositories and content sources
The source files containing a site’s content are stored in one or more git repositories. These repositories can be remote, local, or a combination of both. In a playbook file, you’ll enter several parameters (url, git references, and start paths) that 1. allow Antora to locate and connect to your content source repositories, and 2. provide Antora with the location criteria that resolves to one or more content source roots within a git repository.
If the repository is local, by default Antora will attempt to use the worktree of that repository if the current branch matches one of the branches defined on the content source.
This behavior is configurable.
Antora requires that a local directory is a git repository (thus making the local directory a worktree).
However, you can initialize an empty repository at that location and Antora will then be able to use it (e.g.,
git init . && git commit --allow-empty -m init).
Before configuring a site’s playbook, you’ll want to determine where to set up the content source roots in your repositories.
What’s a content source root?
A content source root is a location in a branch or tag (i.e., a reference) of a repository from where Antora begins looking for content source files. Think of the content source root as the entrance of the store where Antora shops. From the content source root, Antora looks for an antora.yml file, which identifies the component version bucket, then scans for a collection of source files organized in a standard set of directories to add to that bucket.
A repository can have many content source roots. You may have one content source root per branch or tag. Or you may have multiple content source roots per branch or tag defined using multiple start paths. You can also have a combination of both. Where you store the content source roots is up to you.