Component Structure and Configuration
The Couchbase repositories that contain documentation use a standard directory structure and nomenclature. This ensures that Antora can locate the documentation components, collect the content files, and then build docs.couchbase.com.
A documentation component contains AsciiDoc files, their optional assets and examples, one or more optional navigation files, and a component descriptor file per repository. All of the files in a component are versioned together.
While it is common to find all of a component’s files in a single repository, a component can be distributed across several repositories. The Server component is aggregated from the docs-server, couchbase-cli, backup, and asterix-opt repositories.
A component isn’t recognized by a repository or directory. Instead, the presence of a file named antora.yml indicates that the directories and files nested under it are part of a component.
- Component Descriptor
A component must contain a component descriptor file named antora.yml. When Antora finds antora.yml in a repository, it knows it has located a component (or part of component). The component descriptor tags the files under its hierarchy with the specified component name and version.
In these contributing pages, DOCs issues, and the Antora documentation, the term component-version is used when discussing concepts that apply to a version of a component. It’s important to remember that a component’s name and a component’s version may be very different than the names of the repository and branch where it’s stored.
A module is a discrete bundle of content, including text, images, and other source materials, organized in a hierarchy of folders by content format, then by optional topic if needed. A module is stored in a component’s modules directory. A component can contain one or more modules.
- ROOT Module
The ROOT module contains all the content that’s directly associated with the component itself. When pages in the ROOT module are published, these pages are promoted a level above any other modules' pages in that component’s URL.
The pages directory contains a module’s AsciiDoc files. These files are automatically converted to standalone HTML pages. See the Standard Document Structure to learn how to structure an AsciiDoc file.
The partials directory contains AsciiDoc files that aren’t standalone pages. These files are referenced by an include directive from a document in the pages directory.
Multimedia and supplemental files, organized by format, are stored in the assets directory. Photographs, screenshots, and graphic files in assets/images are inserted into pages using the image macro.
Usually, you only edit the component descriptor file, antora.yml, when cutting a release branch and registering or deregistering a navigation file. The component descriptor assigns metadata to each component-version and used to build its page IDs, navigation menus, and URL segments. The following example shows the configuration for Couchbase Server 5.5 that’s specified in its antora.yml file.
name: server title: Couchbase Server version: '5.5' start_page: introduction:intro.adoc nav: - modules/ROOT/nav.adoc
The component coordinate used when creating an xref from a page in one component to a page in another component.
The component name displayed in the component and component version selector menus.
The version coordinate used when locking an xref destination target to a specific version of a page. Writers rarely use this coordinate because in-component xrefs target pages in the same component-version by default, and xrefs that link to pages in other components automatically jump to the latest version of the other component.
The UI uses
versionto sort component-versions in the component version selector menu.
The version name displayed in the component version selector menu. If this key isn’t set, the value of
versionis used instead.
By default, Antora looks in ROOT for the file index.adoc and uses it as the start page for a component. If ROOT doesn’t contain index.adoc (or you don’t want to use that file as the component’s start page), you must explicitly set a start page using its page ID.
The Server component is aggregated from the docs-server, couchbase-cli, backup, and asterix-opt repositories.
When parts of a component are stored in multiple repositories, one antora.yml file acts as the primary component descriptor.
The primary file contains the
The component descriptor files in the other repositories are supplemental.
They only contain
version, so Antora can classify the content files’ component-versions.
The following antora.yml file supplements the primary component descriptor file shown in the previous section.
name: server version: '5.5'
Before releasing a new version of the Couchbase Server component to the production site, all of the repositories that contribute documentation to Server must have a branch containing a matching component-version. Otherwise, the new version will be missing pages and contain broken links.