Working with Our Documentation

The documentation system of BRL-CAD is based on AsciiDoc and Antora.

Installing Antora

  1. Install nvm:

    wget -qO- | bash
    source ~/.bashrc
    command -v nvm
  2. Install the latest Node LTS release:

    nvm install --lts
    node --version
    nvm alias default 14
  3. Install Antora:

    npm i -g @antora/cli @antora/site-generator-default
    antora -v
  4. Install Antora site generator with Lunr:

    npm i -g antora-site-generator-lunr

Building the Docs Locally

  1. Get the code of the docs from GitHub:

    git clone
  2. Generate the HTML files:

    cd brlcad-docs/
    antora build-dev.yml

    As prescribed on build-dev.yml, the output will be stored on the directory html/.

  3. To view the docs, open the HTML files on a browser (the location should be something like this: ~/brlcad-docs/html/docs/index.html).

Editing the Docs

Any text editor is OK, and most of them provide syntax highlighting for AsciiDoc. Some of them provide more advanced features, like live preview.

If you use Emacs, there is an adoc-mode for working with AsciiDoc files. Otherwise you can use one of the editors recommended on this page (which include Atom, Brackets, Eclipse, Visual Studio Code, etc.)

Whenever you make some changes, you need to rebuild the docs and refresh the browser in order to view them. The Bash script utils/ may be used to rebuild the docs automatically whenever there are some modifications.

Submitting Contributions

Assuming that you have write access on the BRL-CAD/brlcad-docs repository, you can commit and push your changes directly. However a better way is to follow the GitHub flow and make a pull request in order to get some review and feedback from other people, before these changes are merged to the main docs.

The workflow could be like this:

  1. Before starting any changes create a new local branch, with a name that somehow describes the changes that are going to be made. For example:

    git clone
    cd brlcad-docs/
    git checkout -b update-the-hacking-book
  2. Then start making the changes and testing them locally (by building the docs with antora build-dev.yml). Commit these changes to the local branch as well.

  3. Push this branch to GitHub:

    git push origin update-the-hacking-book
  4. At this moment, if you go to you will be able to create easily a pull request that aims to merge all the commits from the new branch to the main branch.

  5. Then you can ask someone to review your changes. One way they can review your changes is by checking out your branch and building the docs locally:

    git clone
    cd brlcal-docs/
    git pull
    git branch -a
    git checkout update-the-hacking-book
    antora build-dev.yml
  6. To refine the changes, both of you can make new commits to the branch, and when you push them to GitHub they will appear automatically on the pull request.

  7. When you are happy with the changes, you can merge the pull request and delete the branch from GitHub. You can delete the branch locally as well, like this:

    git checkout main
    git pull -p
    git branch -a
    git branch -d update-the-hacking-book