Couchbase Documentation Site

This is the Antora playbook project (aka site build) for the Couchbase documentation site published at docs.couchbase.com.

Prerequisites

We generally aim to run Node at the "Current LTS (Long Term Support)" version. See nodejs.org/en/about/previous-releases for details on Node’s release schedule.

Run:

node -v

to compare your version with the current installed one. We suggest using nvm to manage versions of node.

Playbook

The playbook, defined in the playbook file antora-playbook.yml, configures the build for this site. The playbook specifies the content sources (repository and branches), site URL, UI bundle URL, global AsciiDoc attributes, and Asciidoctor extensions.

Building the site

This is documented for the Couchbase docs team on [Confluence](confluence.issues.couchbase.com/wiki/spaces/DOCS/pages/2099578216/Building+the+Docs+Site).

If you do not have access to Confluence, you may wish to review the [Antora documentation](docs.antora.org/antora/latest/).

A helper script at scripts/preview simplifies this for some common cases.

Home Docs Component

The home/ directory in this repository contains the source for the Home documentation component. All other content is sourced from separate repositories and branches.

Custom Asciidoctor Extensions

The custom extensions in the lib/ directory process the manpage macro (Couchbase CLI and Backup components), Swagger UI macro, and multi-row table headers.

Tests

Run npm test to run some basic checks on our custom extensions.

Reference Validation

Reference validation, which covers xrefs, includes, and images, is performed automatically when Antora runs. The validation errors will be shown in the log output.

Currently, validation is not enforced, meaning the build will not fail if an invalid reference is detected.

Reading the Log Output

If there are reference violations (e.g., broken xrefs), a report of those violations will be printed to the terminal or CI log. Here’s an excerpt from that report:

[03:39:51.926] ERROR (asciidoctor): target of xref not found: csharp:gs-prereqs.adoc
    file: modules/csharp/pages/querybuilder.adoc
    source: https://github.com/couchbaselabs/docs-couchbase-lite (refname: release/3.0)
[03:26:50.579] ERROR (asciidoctor): target of xref not found: server:fts:fts-using-analyzers.adoc#token-filters
    file: docs/public/modules/clusters/pages/search-service/create-full-text-indexes.adoc
    source: https://github.com/couchbasecloud/couchbase-cloud (refname: main, start path: docs/public)

Each message shows the repository source, the refname, and the path from the root of that repository.

Contributing

Note	somewhat out of date

To learn how to use the playbook and generate the docs site locally, see our contributing guide.

License

Couchbase Server Documentation © 2025 by Couchbase Inc. is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

See the LICENSE file or the Creative Commons CC BY-NC-SA 4.0 license page for details.