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.

Antora relies on the SSH agent to authenticate private repositories on your behalf. If Antora fails because it can’t connect to the private repositories in the playbook, you’re SSH agent probably isn’t running. See SSH Authentication to learn how to configure and run your SSH agent.

Next Step

Commit your changes and push them to your remote repository.