Get the Site Playbook Project

OUT OF DATE

This documentation is out of date

The Docs Site playbook project contains the:

staging playbook
production playbook
site extensions
Home docs component

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

Fork and Clone the Playbook Project

Go to Build the Docs Site if you’ve previously forked and cloned the Docs Site repository. You’ve already completed the steps on this page.

Go to the Docs Site repository on GitHub and click Fork.
Create or select the local folder where you want to store the repository on your device.
Open a terminal and change into the selected folder.
```
$ cd path/to/folder
```
Go to your repository on GitHub, and click Clone or download.
Click the Clipboard icon to copy the repository’s Git URL.
In your terminal type git clone, paste the copied URL, and press Enter.
```
$ git clone git@github.com:this-is-you/docs-site.git
```
Change into the repository folder created by the clone operation.
```
$ cd docs-site
```

Configuring the Playbook

To preview your changes on the site locally, you need to configure the playbook to use your local repository.

Copy the Antora playbook, antora-playbook.yml, and save it in the docs-site repository.
Rename it local-antora-playbook.yml.
Open local-antora-playbook.yml in Atom or your editor.
Under sources, find the url key that matches the upstream repository you plan to submit your changes to. Replace the repository URL with either the relative system path from the playbook project to your local repository or the absolute path. For example, if you’re making changes to files in the docs-server repository, you’d enter:
```
- url: ./docs-server
```
If there isn’t a branches key on the line directly below the url key, add it and assign it the list of version branch names, except for the version branch your working branch is based on. In place of the remote version branch, use the value of HEAD. HEAD tells Antora to use your working branch. For example, if your working branch is based off of the docs-server release/5.5 branch, you’d assign the following values to branches:
```
- url: ./docs-server
  branches: [release/7.1, release/7.0, release/6.5, HEAD]
```
If there is a branches key on the line directly below the url key, replace the version branch name you based your working branch on with HEAD.
The build process makes use of a Kroki server to generate diagrams from structured textual descriptions. There is a section for the Kroki setup in the playbook:
```
asciidoc:
  attributes:
    # other settings
    kroki-server-url: http://3.91.133.254:9500
    kroki-fetch-diagram: true

  extensions:
     # other settings
  - asciidoctor-kroki
```
In your own playbook, set the kroki-server-url address to the public Kroki server, as shown below:
```
kroki-server-url: https://kroki.io
```
Save the playbook.

Lightweight Local Playbook

You may have to iterate over amending the Antora playbook file a number of times, commenting out repos to which you do not have access. An easier approach could be starting with an intentionally minimalist playbook, and only adding the repos that you’re planning to work on. This will have to include the docs-server repo which, amongst other things, contains the site navigation.

For example, to work on local copies of our ten SDK docs repos, and the Server docs, and also include couchbase-cli in your local docs build, take a look at our example local-staging-antora-playbook.yml file.

Next Steps

Set Up Your Local Repository