https://github.com/bbatsov/docs.projectile.mx
Projectile's documentation site
https://github.com/bbatsov/docs.projectile.mx
antora asciidoc emacs projectile
Last synced: 10 months ago
JSON representation
Projectile's documentation site
- Host: GitHub
- URL: https://github.com/bbatsov/docs.projectile.mx
- Owner: bbatsov
- Created: 2020-05-29T07:03:44.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-02-18T07:48:31.000Z (11 months ago)
- Last Synced: 2025-03-06T16:07:04.906Z (10 months ago)
- Topics: antora, asciidoc, emacs, projectile
- Language: Handlebars
- Homepage: https://docs.projectile.mx
- Size: 2.78 MB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
= docs.projectile.mx
The site is generated from the AsciiDoc files in the
link:https://github.com/bbatsov/projectile/tree/master/doc[doc] folder of
Projectile's GitHub repo and is published to https://docs.projectile.mx.
link:https://antora.org[Antora] is used to convert the manual into HTML. The
filesystem layout is described https://docs.antora.org/antora/3.1/component-structure/[here].
To make changes to the manual you simply have to change the files under `doc`.
The manual will be regenerated manually periodically.
== Building the Site
NOTE: You'll need to install `node.js` to build the site.
You can build the documentation locally from this repository:
[source]
----
$ cd docs.projectile.mx
$ make build
----
== 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:
[source]
----
- url: https://github.com/bbatsov/projectile.git
branches: master
tags: ['v1.7.0', 'v1.8.0']
start_path: docs
----
TIP: You need to add one such block for each new Projectile module you're adding to the docs site.
After releases of Projectile you also need to update the default landing
version (it should always be the latest version).
== 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`.