Repositories and Content Source Roots

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.

Before configuring a site’s playbook, you’ll want to determine where to set up the content source roots in your repositories.

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.