Distributed Component Versions

When a component version’s source files are stored in multiple content roots (i.e., multiple repositories, multiple start pages, etc), it’s referred to as a distributed component version.

A common use case of a distributed component version is when most of its source files are stored in one repository, but a number of examples (examples family directory) and tutorials (pages family directory) are stored in another repository managed by a training team. Antora has no problem combining the source files from both storage locations into a single component version. This capability is provided by the simple, but-oh-so-powerful component version descriptor file, antora.yml.

Recall that an antora.yml file specifies the component name and version of a component version. If Antora discovers two or more antora.yml files that specify an identical component name and version, it considers all of the files in the subsequent standard directory sets to belong to the same component version, even though the source files were collected from multiple locations.

When the source files of a component version are distributed, only one of the antora.yml files should specify the optional configuration keys, such as title and nav, in addition to the required component name and version. All of the other antora.yml files that mark the locations of the component version’s source files must only specify the component name and version. Conflicting or duplicate optional configuration keys may produce unpredictable results.

When setting up a distributed component version, each content source root must contribute a unique set of files (aside from antora.yml). In other words, the content source roots cannot overlap when combined.

Antora will fail with an error if it finds two or more source files with same resource ID. These are identical filenames that belong to the same family and module in the distributed component version. This also occurs if Antora discovers a module that has two or more navigation files with identical filenames. See Duplicate resources for more information about this situation.