https://github.com/clojure-emacs/docs.cider.mx
CIDER's documentation site
https://github.com/clojure-emacs/docs.cider.mx
antora cider clojure documentation emacs user-manual
Last synced: 6 months ago
JSON representation
CIDER's documentation site
- Host: GitHub
- URL: https://github.com/clojure-emacs/docs.cider.mx
- Owner: clojure-emacs
- Created: 2019-05-27T12:11:18.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-30T07:34:24.000Z (8 months ago)
- Last Synced: 2025-04-30T08:42:39.288Z (8 months ago)
- Topics: antora, cider, clojure, documentation, emacs, user-manual
- Language: Handlebars
- Homepage: https://docs.cider.mx
- Size: 14.8 MB
- Stars: 1
- Watchers: 10
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
= CIDER Documentation Site
The site is generated from the AsciiDoc files in the link:https://github.com/clojure-emacs/cider/tree/master/doc[doc] folder of nREPL's GitHub repo and is published to https://docs.cider.mx.
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/
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
link:https://github.com/clojure-emacs/cider/blob/master/doc/modules/ROOT/nav.adoc[nav.adoc].
== Installing Antora
Installing the Antora is super simple:
[source]
----
$ make npm
----
Check out https://docs.antora.org/antora/3.1/install/install-antora/[the detailed installation instructions]
if you run into any problems.
== Building the Site
You can build the documentation locally from this repo.
[source]
----
$ 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:
[source]
----
$ 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 https://docs.antora.org/antora/latest/antora-container/[official docs].
== 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/clojure-emacs/cider.git
branches: master
tags: ['v1.7.0', 'v1.8.0']
start_path: docs
----
TIP: You need to add one such block for each new CIDER 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`.