Test Your Changes Locally

    +

    If you’ve never built the site on your device, complete the Install Antora and Get the Site Playbook Project steps first.

    Configuring the Playbook

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

    1. Copy the staging playbook, staging-antora-playbook.yml, and save it in the docs-site repository.

    2. Rename it local-antora-playbook.yml.

    3. Open local-antora-playbook.yml in Atom or your editor.

    4. 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
    5. 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/4.*, release/5.0, release/5.1, HEAD]
    6. 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.

    7. Save the playbook.

    Generating the Site

    1. Open a terminal and switch (cd) to the docs-site folder.

    2. Run Antora with your local playbook:

      docs-site $ 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.

      1. A warning indicates that a document contains invalid AsciiDoc syntax. Antora will continue to build the site, but pages generated from invalid AsciiDoc will not display correctly.

      2. Errors cause the site build to fail.

    4. If no errors terminate the build, site generation is complete when the command prompt ($) reappears in the terminal.

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

      docs-site $ cd public
    6. On some operating systems, you can open the site directly from the command line by typing open and the name of an HTML file.

      public $ open index.html

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

    7. Review your changes on the local site.

    8. Make additional edits if needed, and fix any documents that report warnings.

    9. Run Antora again and review your changes in the site.

    When you’re satisfied with your work and fixed any reported errors, it’s time to send your changes upstream for review.

    Since some of the respositories listed in the playbook are private, Antora will look for git credentials to use to connect to those repositories. If Antora fails because it can’t connect to the private repositories, you’re git credentials likely aren’t configured. See git credentials to learn how to configure the git credentials for Antora to use.

    Lightweight Local Playbook

    You may have to iterate over ammending 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 nine 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.