Component Structure and Configuration
Terminology and Structure
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.
- Component
-
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.
- Component-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.
- Module
-
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.
- Pages
-
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.
- Partials
-
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.
- Assets
-
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.
- Examples
-
Non-AsciiDoc files, such as source code, are stored in the examples directory. These files are often inserted into code blocks using an include directive.
- Navigation
-
A navigation file, often named nav.adoc, contains one or more AsciiDoc lists. Antora uses these files to build the site’s component navigation menus.
Configuring a Component
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.adocname-
The component coordinate used when creating an xref from a page in one component to a page in another component.
title-
The component name displayed in the component and component version selector menus.
version-
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. version_title-
The version name displayed in the component version selector menu. If this key isn’t set, the value of
versionis used instead. start_page-
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.
nav-
The nav key accepts a list of navigation file paths. The order of the values dictates the order the contents of the navigation files are assembled in the published component menu.
Supplemental Component Descriptor Files
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 name, title, version, and nav configuration.
The component descriptor files in the other repositories are supplemental.
They only contain name and 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.