Documentation Components and Repositories
Antora uses content organized into documentation components when it generates a documentation site.
What is a documentation component?
A documentation component typically represents the documentation for a product, application, project, microservice, or training course. It’s a collection of files grouped into modules and families that share common metadata. Antora can generate a site that only contains one documentation component or a site that contains as many documentation components as you require.
Standard directory structure of a documentation component
Antora extracts the metadata that defines a documentation component from its component descriptor file (antora.yml) and the standardized directory structure used to store the component’s source files. Antora also uses this structure to automatically assign preset behavior to the files stored in each directory. Figure 1 shows an example of this standard directory structure.
At a minimum, a documentation component contains:
-
a component descriptor file (antora.yml),
-
a modules directory,
-
at least one module directory, such as ROOT or a named module (that is, a module directory that you name), and
-
at least one family subdirectory (attachments, examples, images, pages, or partials).
modules directory
Except for antora.yml, all of a component’s source files must reside in the modules directory. This directory allows Antora to locate a documentation component that is stored in a repository or directory with other files, such as an application’s source code.
Named and ROOT module directories
The modules directory can contain a single module directory or as many module directories as you require.
A module directory represents a module in that documentation component.
A module is a discrete bundle of content, such as text, images, and other source materials, that is usually related by concept, stage, feature, or workflow.
The directory name of a module is used as the module coordinate in a resource ID and, with the exception of the special ROOT module, appears in the site’s output path.
The ROOT directory is a special module directory. Its name doesn’t appear in the site’s output path. Instead, it becomes the parent of any named modules in that component.
Family directories
Each module directory, whether ROOT or a module you name, can contain any of the following family subdirectories:
Antora automatically assigns preset behavior to the files in these directories. For example, AsciiDoc files in pages are automatically converted to individual HTML pages.
Navigation file
A module can contain none, one, or numerous navigation files. A navigation file is an AsciiDoc file (nav.adoc) that is stored in the directory of the module, but not in any of the module’s family subdirectories. In order to be displayed in the component’s navigation menu, the navigation file must be declared in the component descriptor.
antora.yml file
The component descriptor file tells Antora that the contents of the repository or directory are a documentation component. This file contains crucial metadata that’s applied to all of a component’s files. See Component Descriptor: antora.yml to learn about the required and optional information you can assign to a component.
|
Distributed component
While all of a documentation component’s source files can be stored in a single repository, it isn’t a requirement.
Antora can collect a component’s source files from 5, 25, and even more repositories.
That means a few of a component’s modules could be store in one repository, while the examples directory of another module is stored in a tutorial repository that’s maintained by a training team, and then that same module’s pages could be stored in pages directories across three different repositories.
When a documentation component’s source files are stored in multiple repositories, it’s referred to as a distributed component.
This capability is provided by the simple, but-oh-so-powerful component descriptor file, antora.yml.
|