Multiple Start Paths

The start_path key only lets you specify a single path in your playbook for a given content source. In contrast, the start_paths key lets you specify multiple paths. The multiple paths can be even further consolidated using glob patterns, which Antora resolves to one or more fixed paths.

The start_paths key is mutually exclusive with the start_path key. If both the start_path and start_paths keys are present on a content source, only the start_paths key is used.

Like with the singular start path, the start paths are searched per reference (i.e., branch or tag). That means a component version descriptor must be found at each start path for each reference.

Typically, when using multiple start paths, you’ll only be using a single reference anyway (e.g., master). If you do use multiple references in this scenario, the assumption is that each reference shares the same layout.

You can use start_paths to store all versions of a component in a single repository branch using folders instead of using multiple branches. Although you may miss out on some of the advantages of the version control system, this arrangement can make it easier on writers who are frequently updating multiple versions of the documentation at once.

In this scenario, you’d provide a single value for the branches key and use the start_paths key to tell Antora which directories in the branch to use as content roots. If the version folders are named consistently, it becomes easy to match them using a glob pattern.

Here’s an example of a repository layout that uses folders to store documentation versions:

You can take it a step further and store all components in a single repository branch using folders instead of using multiple repositories. If those components have versions, you’d likely use subfolders to store the versions as well. This arrangement works best if all the documentation is maintained by the same team or individual and the distributed nature of git just gets in the way. It might also be used for a monorepo, in which the source code for multiple products is stored in the same repository. Antora can discover the documentation wherever it starts within that structure.

In this scenario, you’d again provide a single value for the branches key and use the start_paths key to tell Antora which directories in the branch to use as content roots. Only this time, the content source roots will match different components (and possibly versions), not just versions of a single component.

Here’s an example of a repository layout that uses folders to store components:

Naturally, the repository may have many other files and folders that do not pertain to the documentation.

The following restrictions apply to how Antora implements path globbing against the full range of supported basic and advanced globbing rules:

Wildcard matching reduces the number of values you need to assign to a start_paths key. For instance, if you have multiple components stored in a branch, you could list them all in a comma-separated list like the one shown in Example 2.

Or, as shown in Example 3, you could use a wildcard segment and reduce the number of values you need to declare.

Wildcard matching offers the possiblity of registering new content source roots as you add them, providing you keep the pattern consistent.

Brace expressions can specify an explicit list of items separated by commas to expand (docs/product-{a,b,c,f}) or a range of items to expand (docs/product-{a..f}). A brace expression may not consist of only a single item, even if that item contains a wildcard (e.g., docs/product-{a} and docs/product-{a*} are not brace expressions).

Brace expressions may be nested (e.g., docs-*/v{{1..9},{1..9}{0..9} matches the subfolders v1 through v99 of root folders that match the name docs-*). In this case, each permutation for each nested brace expression is tested.

When you use braces in a start_paths value, all entries within the braces must exist when expanded (unless the segment is preceded by a wildcard segment).

If you specify docs/product-{a,b} as a start_paths value, the following paths must be present within the repository:

You can use a prefix in your file path before a brace expression to simplify what Antora checks for in the expression.

You can also use wildcards in brace expressions to help expand values.

The start_paths pattern in Example 5 would match the following paths:

Use negated patterns to exclude patterns previously matched. This approach is useful if you want to match all directories except for those that match a certain pattern.