CIDER Documentation Site

The site is generated from the AsciiDoc files in the doc folder of nREPL’s GitHub repo and is published to https://docs.cider.mx. 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.

Note	If you want to make changes to the manual’s page structure you’ll have to edit nav.adoc.

Installing Antora

Installing the Antora is super simple:

$ make npm

Check out the detailed installation instructions if you run into any problems.

Building the Site

You can build the documentation locally from this repo.

$ cd docs.cider.mx
$ 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:

$ cd docs.cider.mx
$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --cache-dir=./.cache/antora antora-playbook.yml

Note that despite the message saying Open file:///antora/build/site/index.html in a browser to view your site., you you should actually look for build/site/index.html in the current directory. (that’s because we’ve mounted the current directory as /antora in the container)

Tip	You can read more about running Antora in a container in the official docs.

Updating the Playbook

The site only builds the tags listed in antora-playbook.yml, one block per project:

- url: https://github.com/clojure-emacs/cider-nrepl.git
  branches: master
  tags: ["v0.62.2", "v0.63.0", "v0.64.0"]
  start_path: doc

add-release.mjs adds a release to its project’s block. The publish workflow runs it when a project’s release workflow sends a release event with the project and the tag in its payload, which cider-nrepl’s does, given a DOCS_DISPATCH_TOKEN secret that can write to this repository. For CIDER, run the publish workflow manually with the project and the tag, or run the script locally and commit the result:

$ node add-release.mjs cider v2.1.0

A patch release replaces the tag of its minor version, since both are published as the same docs version.

The projects' antora.yml files take the docs version from the tag (v2.1.0 becomes 2.1), so a release doesn’t touch them, and leave master unversioned. extensions/master-display-version.js calls that version "master" in the version menu.

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

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.