Configure Your Antora Playbook

The docs-site repository contains necessary files for building and publishing the Couchbase Documentation site.

For example, it contains the:

staging playbook
production playbook
site extensions
home docs component

To generate a local copy of the documentation site on your computer, you need the antora-playbook.yml file. This YAML file provides key site configuration information to Antora.

To generate the documentation site on your device, you need its playbook. The playbook provides the site configuration to Antora.

Clone the Playbook Project

Just like any other documentation repository, you need to get the docs-site repository onto your computer:

Go to the docs-site repository.
Follow the instructions in Clone the Repository.

Contributors from outside Couchbase need to fork documentation repositories to contribute changes. If you’re a Couchbase employee, DO NOT fork repositories to contribute to Couchbase Documentation.

Configure a Local Antora Playbook

To generate a local copy of the documentation site and preview your changes, you need to configure a playbook file to use your local repositories.

To configure a local playbook file:

Create a copy of the antora-playbook.yml file inside the top-level folder of the docs-site repository on your computer.
Rename the copy to local-antora-playbook.yml.

This stops your local playbook from being detected by Git. You can safely make changes to the file without worrying about committing those changes to the docs-site repository.
Open your new local-antora-playbook.yml in VS Code or your preferred editor.
Inside the local-antora-playbook.yml, under antora > extensions, delete the entry for the "@antora/collector-extension".
Choose whether to remove any repositories from your local build.
Set the playbook to use the local version of the repository where you made your changes.
(Optional) Set up Kroki to build diagrams.
Save the playbook file.

Remove a Repository’s Files from Your Local Build

To remove the files from a repository from your local build and speed up the build process:

Under sources, locate the url key entry for the repository you want to remove.
Add a hash (#) to the start of the line with the -url key.

If the -url key is followed by a branches or start_path key, add a hash (#) to the start of those lines, too.

For example, to remove the couchbaselabs/docs-style-guide files from a local build:

---
sources:
  - url: .
    branches: HEAD
    start_path: home
  #- url: https://github.com/couchbaselabs/docs-style-guide
    #branches: main
    #start_paths: [styleguide, ui-ux, pendo]
---

You can also delete the entire -url key entry for a repository to remove it from your build - but keep in mind that you might need to add it back in later for other documentation work.

Use Your Local Repository in a Build

To use the files from your local repository in a build and preview your changes:

Under sources, locate the url key entry for the repository you modified and want to preview.
Change the -url key to either:
1. The relative system path from your docs-site repository to the local repository.
2. The absolute system path to the local repository.
  
  For example, if you store all of your Documentation repositories in the same parent folder on your computer, and you modified files in the docs-server repository:
  - url: ../docs-server branches: [release/7.6, release/7.2, release/7.1, release/7.0] - url: https://github.com/couchbase/docs-sdk-common branches: [temp/7.5, release/7.2, release/7.1.2, release/7.1, release/7.0, release/6.6, release/6.5]
On the line following the -url key, add a branches key, if there is not one already.
In the branches key, set the value to HEAD.

You can keep additional version branches or set your local repository to the only branch to build. If you do keep multiple branches, do not keep the branch that you used as a base for your local changes.

For example, if your working branch was based off of docs-server release/7.6 and you wanted to keep the other release branches in your build:
```
- url: ../docs-server
    branches: [HEAD, release/7.2, release/7.1, release/7.0]
- url: https://github.com/couchbase/docs-sdk-common
    branches: [temp/7.5, release/7.2, release/7.1.2, release/7.1, release/7.0, release/6.6, release/6.5]
```
To use only your working branch, your YAML should look like the following:

- url: ../docs-server
    branches: HEAD
- url: https://github.com/couchbase/docs-sdk-common
    branches: [temp/7.5, release/7.2, release/7.1.2, release/7.1, release/7.0, release/6.6, release/6.5]

Set Up The Kroki Server to Add Diagrams to Your Local Build

The Couchbase Documentation uses Kroki to generate diagrams from structured textual descriptions for easier maintenance.

The antora-playbook.yml uses the production Kroki server set up by Couchbase, but using this server will cause failures in your build and greatly extend the build time.

You can choose to use the public Kroki server, or comment out the Kroki configuration with hashes (#) to remove Kroki diagrams from your build.

To use the public Kroki server:

Under asciidoc > attributes, find the kroki-server-url key.
Set the kroki-server-url key to https://kroki.io:
```
kroki-server-url: https://kroki.io
```

If the public Kroki server is down or you just do not want diagrams in your build, add a hash before the following key entries in the playbook:

kroki-server-url (under asciidoc > attributes)
kroki-fetch-diagram (under asciidoc > attributes)
asciidoctor-kroki (under asciidoc > extensions)

Lightweight Local Playbook Example

You might have to comment out a number of repositories from the base Antora playbook file before you can successfully run a local build.

You can choose to start with a much more minimalist playbook to make things easier, and only add the repositories that you’re planning to work on.

For an example lightweight local playbook, see the example local-staging-antora-playbook.yml file.

Next Steps

Set Up Documentation Repositories