nREPL.org

The site is generated from the AsciiDoc files in the doc folder of nREPL’s GitHub repo and is published to https://nrepl.org. Antora is used to convert the manual into HTML. The filesystem layout is described at https://docs.antora.org/antora/3.1/component-structure/

To make changes to the manual you simply have to change the files under doc. The manual will be regenerated manually periodically.

Building the Site

Note	You’ll need to install node.js to build the site.

You can build the documentation locally from this repo.

$ cd nrepl.org
$ make build

To check the generated site you can simply open build/site/index.html in your favourite browser.

Deploying the Site

Note	You’ll need commit access to the repository for this to work.

The site is automatically deployed to GitHub pages using a GitHub Action. The action will be triggered by any push to the master branch. It can also be triggered manually if needed.

Using Docker

If you prefer not to install Antora on your local machine, you can build the documentation inside a Docker container like this:

$ docker run --rm -t -v $(pwd):/build/site antora/antora:3.1.10 --fetch /docs/antora-playbook.yml

Updating the Playbook

When cutting new releases you’ll have to updated antora-playbook.yml to mention their relevant tags from which the documentation needs to be build. Here’s how this looks for one of the projects:

- url: https://github.com/nrepl/nrepl.git
  branches: master
  tags: ['v1.7.0', 'v1.8.0']
  start_path: docs

Tip	You need to add one such block for each new nREPL module you’re adding to the docs site.

Troubleshooting

The most common mistake that people make is to forget to update the version of an Antora docs module after cutting a release. This will result in an error saying you’ve got the same version in two branches (e.g. master and v1.0). Fixing this is pretty simple - just update the version to master in antora.yml.