Component Structure and Configuration
- OUT OF DATE
This documentation is out of date |
Terminology and Structure
All Couchbase Documentation repositories use a standard directory structure and some common files and features. This ensures that Antora can locate the documentation components, collect the content files, and then build docs.couchbase.com.
Here are some key terms for Couchbase Documentation repositories and files:
- Component
-
A component contains:
-
AsiiDoc content files
-
Assets, like images
-
Examples, like code samples
-
Navigation files
-
A component descriptor file (
antora.yml
).All of the files in a component are versioned together, based on the
antora.yml
.Components can sometimes be distributed across several GitHub repositories. For example, the component for the Server documentation is built from
docs-server
,couchbase-cli
,backup
, andasterix-opt
.
-
All components are identified by antora.yml
- not a repository or directory.
- 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
-
A component version is a specific version of the documentation stored in a component. Component names and component versions do not always map to a GitHub repository and branch. They can be set and modified independently from the GitHub repository and branch structure.
- Module
-
Modules organize content files, including text, images, and code samples, inside a component. Modules are stored under the
modules
folder in a component. Components can contain multiple modules. - ROOT Module
-
The
ROOT
module contains necessary top-level content associated with a component. For example, theROOT
module contains the navigation files for a component. When pages in theROOT
module are published, these pages are promoted a level above any other modules' pages in that component’s URL. - Navigation Files
-
The
ROOT
module usually contains a navigation file callednav.adoc
. It contains an unordered list of cross references to documentation pages in specific modules inside the component. Antora uses navigation files to build navigation menus for a component. For more information about working with navigation files, see Update a Navigation File. - Pages
-
A
pages
directory exists under a specific module in themodules
directory. Thepages
directory specifically contains any AsciiDoc text files for whole pages in the Couchbase Documentation. For more information about structuring files in thepages
directory, see Standard Document Structure. - Partials
-
A
partials
directory exists under a specific module in themodules
directory. Thepartials
directory contains AsciiDoc files that can be inserted inside files in thepages
directory. This is helpful for content reuse and single-sourcing information across multiple pages. For more information about partials, see Include Examples and Partials. - Assets
-
An
assets
directory exists under a specific module in themodules
directory. Theassets
directory can contain sub-directories, likeimages
, that organize images and other multimedia files for the documentation. You can insert files in these directories into files in thepages
directory. For more information about how to insert images into documentation, see basics.adoc#images. - Examples
-
An
examples
directory exists under a specific module in themodules
directory. Theexamples
directory contains non-AsiiDoc or image files, usually source code, for inserting as examples into the documentation. For more information about how to work with code examples, see Code Blocks for Example Code.
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.adoc
name
-
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
version
to 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
version
is 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.