https://github.com/nrepl/nrepl.org
nREPL's official site
https://github.com/nrepl/nrepl.org
antora asciidoc clojure nrepl
Last synced: 11 days ago
JSON representation
nREPL's official site
- Host: GitHub
- URL: https://github.com/nrepl/nrepl.org
- Owner: nrepl
- Created: 2018-07-13T05:33:58.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-09-04T10:36:23.000Z (5 months ago)
- Last Synced: 2025-10-01T12:38:09.703Z (4 months ago)
- Topics: antora, asciidoc, clojure, nrepl
- Language: Handlebars
- Homepage: https://nrepl.org
- Size: 3.15 MB
- Stars: 0
- Watchers: 6
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
= nREPL.org
The site is generated from the AsciiDoc files in the link:https://github.com/nrepl/nrepl/tree/master/doc[doc] folder of nREPL's GitHub repo and is published to https://nrepl.org.
link:https://antora.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.
[source]
----
$ 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:
[source]
----
$ 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:
[source]
----
- 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`.