Test Your Changes Locally


      To build the Couchbase Documentation site on your computer, make sure that you have:

      Then, you need to start by configuring your Git credentials in Antora.

      Configure Your Git Credentials

      If you left some remote repositories in your local playbook file, make sure you configure your GitHub credentials so Antora can access those repositories during a build:

      1. Go to the GitHub webpage for the remote repository to make sure you have access.

      2. Configure a classic personal access token (PAT) for your GitHub account with the repo scope.

        Keep the PAT somewhere where you can copy it again later.

        Make sure you also authorize your token to work with SAML single sign-on.

      3. Open a Git Bash window.

        You should have automatically installed Git Bash when you installed Git on your computer.

      4. Paste the following command:

        git config --global credential.helper store && \
        git ls-remote -h https://github.com/couchbase/couchbase-operator > /dev/null && \
        git config --global --remove-section credential
      5. Paste your PAT after the first prompt, then hit Enter twice.

        This stores your PAT in the $HOME/.git-credentials file on your computer.

      If you run into issues with a private repository when trying to run another build later, run the following command through Git Bash:

      git config --global credential.helper store &&
      echo -n 'Repository URL: ' && read REPLY
      && git ls-remote -h $REPLY > /dev/null

      Enter the URL of the repository that’s causing your build to fail when prompted.

      Generate a Local Build with Antora

      To generate a local build of the documentation site, as configured by your local playbook file:

      1. Open a terminal.

      2. Navigate to the folder where you cloned the docs-site repository:

        $ cd <path/to/docs-site/repository>
      3. Enter the following command to tell Antora to run using your local playbook file:

        $ antora local-antora-playbook.yml

      Antora starts by showing the cloning progress of each repository in the playbook. Then, any AsciiDoc or Antora warning or error messages for each file in the build will show.

      • Warnings indicate that a file contains invalid AsciiDoc syntax. The site still builds, but pages might not display correctly if they have incorrect syntax.

      • Errors can indicate broken links or other issues. Some errors might cause the site build to fail.

      When the site build finishes, Antora should display a message saying Site generation complete!. The command prompt reappears in your terminal.

      Review the Changes in Your Build

      Some terminal programs might display a prompt that lets you directly open the site build from the terminal.
      1. Using your terminal or a file explorer, inside the docs-site repository, navigate to the public folder.

      2. Do one of the following:

        1. If your operating system supports it, enter the following command into your terminal:

          $ open index.html
        2. In your file explorer, double-click index.html.

        Your web browser should open your local build just like any other website.

      3. Review the changes in your local build to make sure everything appears as expected.

      You can make changes to the files in a repository and re-run Antora locally as many times as you need.