docs.nrepl.org

The site is generated from the AsciiDoc files in the doc folder of nREPL’s GitHub repo and is published to https://docs.nrepl.org. The docs used to live at https://nrepl.org, which is now nREPL’s landing page (nrepl/nrepl.org) and redirects the old docs URLs here. 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 docs.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

The site only builds the nREPL tags listed in antora-playbook.yml, and nREPL’s release workflow adds them: it sends a release event with the new tag to this repository, and the publish workflow adds the tag with add-release.mjs, pushes the playbook change and publishes the site. A patch release replaces the tag of its minor version, since both are published as the same docs version. Prereleases aren’t sent.

You can also add a release by running the publish workflow manually with a tag, or by running the script locally and committing the result:

$ node add-release.mjs v1.9.0

nREPL’s doc/antora.yml takes the docs version from the tag (v1.9.0 becomes 1.9), so a release doesn’t touch it, and leaves master unversioned. extensions/master-display-version.js calls that version "master" in the version menu.

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.

The Theme

The site uses Antora’s default UI with the files under supplemental-ui on top of it, so it matches https://nrepl.org: the same colors, header and logo, plus a dark theme.

• The default UI compiles its CSS variables away, so supplemental-ui/css/site-extra.css restates each of its color rules with the palette at the top of the file. The colors are written as light-dark(light, dark), so they follow the system preference, or the theme picked with the toggle in the header (it’s saved in localStorage, same as on nrepl.org).

• The code colors have the same names as in nrepl.org’s assets/css/main.css. If they change there, copy them over.

• The few dark theme values that aren’t colors (a filter for the default UI’s icon images, the chevron of the version menu, and the logo on each version’s home page, which has a dark wordmark) are set twice: once for the system preference and once for the toggle. A new one has to go in both places.

• head-meta.hbs loads site-extra.css after the tabs and DocSearch stylesheets, so its rules win, and applies a saved theme before the page is drawn. footer-content.hbs has the toggle’s click handler.

• Every file under supplemental-ui has to be listed in both playbooks.

The UI bundle is a snapshot of the default UI’s master, so its fixes arrive on their own. The flip side is that something new it adds with a color of its own shows up in the stock colors until a rule for it is added here. Its stylesheets show which rules set colors, and vars.css there says what each color is for.

Forking the default UI would have made the colors a matter of editing vars.css, but the fork would have to be built with the UI’s own (rather old) toolchain and kept up with upstream by hand.

Fixing the Docs of a Release

A release tag can’t be changed, so a fix to the docs of a release that’s already out goes on an -antora tag: a commit with the fix on top of the release tag, tagged vX.Y.Z-antora, which replaces the release tag in the playbook. nREPL’s release workflows skip -antora tags, so pushing one doesn’t publish anything but the docs.