Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Build the Documentation Site Locally

    • OUT OF DATE
      +
      This documentation is out of date

      Configure Your git Credentials

      Since some of the repositories listed in the playbook file are private, you’ll need to configure credentials in git so Antora can connect to those repositories.

      First, make sure you can visit the private repositories hosted on GitHub in your browser. If you cannot, you’ll need to request access. Once you have access, you may proceed to the next step.

      Next, generate a personal access token for your account on GitHub. The token must have the repo scope. See creating a personal access token for the command line for detailed instructions. Keep the token handy to complete the next step.

      Finally, run the following command to add your token to your git configuration:

      git config --global credential.helper store && \
git ls-remote -h https://github.com/couchbase/couchbase-operator > /dev/null && \
git config --global --remove-section credential

      Enter the personal access token in the first prompt, then press Enter twice. You no longer need to keep the personal access token on hand since it’s stored in the file $HOME/.git-credentials.

      If you’ve completed all the steps above, you should now be able to use Antora to connect to private repositories on GitHub. And that means you can build the documentation site on your own machine, which the next section covers.

      Run Antora

      1. Open a terminal and switch into the docs-site folder.

        cd path/to/docs-site

      2. Run Antora, using the antora command with your local playbook:

        antora local-antora-playbook

      3. The cloning progress of each component repository is displayed in the console, followed by any AsciiDoc or Antora warning and error messages. The site generation is complete when the command prompt ($) reappears in the terminal.

      4. Antora generated the site into a directory named public. Switch to it.

        cd public

      5. On some operating systems, you can open the site directly from the command line by typing open and the name of an HTML file.

        open index.html

        Or, you can navigate to and open index.html using your file explorer or browser.

      Now that you’re set up to build the full site on your own machine, you’ll also be able to use a personal playbook to test your local documentation changes.

      If you notice that some of the diagrams are not being displayed, then it is possible that you have not set up the Kroki server correctly. You’ll find instructions on the Kroki setup in here.