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/

Note	To make changes to the nREPL docs you simply have to change the files under doc.

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 -u $(id -u) -v $(pwd):/antora antora/antora:3.2.0 --fetch antora-playbook.yml

Updating the Playbook

When cutting a new release you’ll have to update antora-playbook.yml to mention its tag, so the documentation for that version gets built:

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

The site is rebuilt on every push to this repository, once a day, and whenever the nrepl repository asks for it, so doc changes on nREPL’s master show up without anyone triggering a build.

Previewing Local Changes

antora-playbook-local.yml builds the site from the nREPL checkout next to this repository (../nrepl), whatever branch it has checked out, uncommitted changes included:

$ npm run antora -- antora-playbook-local.yml

Only that one branch is built, so the version menu stays empty.

Troubleshooting

The most common mistake is forgetting to set the docs version in doc/antora.yml on the release commit (or to reset it to ~ afterwards). The former leaves the release out of the version menu for good, since the tag can’t be changed; the latter makes Antora complain that two branches claim the same version.