Auto-build and host pretty HTML documentation using AsciiDoc, GitHub pages & GitHub Actions

Photo by Pixabay from Pexels

How to automatically build AsciiDoc into HTML on every Git commit using GitHub actions, and host it using GitHub pages.

Example of the end result;

• docs.upsilonproject.io which is built from https://github.com/upsilonproject/upsilon-docs
• https://redhat-cop.github.io/agnosticd/ which is built from https://github.com/redhat-cop/agnosticd

Setup AsciiDoc in your repository

GitHub favours Markdown the the README — so in my projects I keep a README.md that describes the project like normal. , but I use AsciiDoc for the “real” documentation. My real documentation spans multiple files, so I use a docs directory in my repositories. As your project grows, you’ll find you cannot document everything in the README.md .

While your README.md serves as a high level introduction, or a quickstart to your project, your docs is something different — much more detailed, how to use your project, troubleshooting etc. I use AsciiDoc because I’ve found it’s better than markdown for more detailed project documentation.

If you’re not used AsciiDoc before, it’s similar to Markdown, but has lots of extra syntax that allows for much more rich documentation. For example, tables of contents, better control over heading levels, links to headings, heading numbering, etc.

You can see the syntax is similar to markdown, but a bit different;

docs/index.adoc — Note, the filename in the Gist uses (dot) because otherwise Github renders the .adoc file.

There is quite a lot of preamble/setup in this AsciiDoc example that may not be needed in your use case. However, I found these are pretty helpful for larger project documentation though.

Note: Obviously you can see that this docs/index.adoc includes docs/installation.adoc and docs/basic_setup.adoc . This is an example of scalable, multi-page documentation that is easy with AsciiDoc that just isn’t possible with GitHub Markdown alone.

Style your docs with a bit of CSS

People will spend more time reading your documentation if it doens’t look like garbage. You can add CSS so that your documentation is responsive (works on Mobile, tablet, etc), and any sized browser window. Again, increasing readability massively.

Here’s a snippit of some useful styles with a grid layout to get you started (it’s what I use for docs.upsilonproject.io);

Makefiles make it easy to build the docs locally

I really like using Makefiles for lots of stuff. Let’s use a makefile here, so we can just use the make command to make our docs.

docs/Makefile

This means you can simply run make locally to build some nice HTML5 documentation :-) Open index.html to see the built documentation.

GitHub Actions make it easy to build the docs on Github

GitHub Actions can be used to automate tasks every time you commit to GitHub. We can use GitHub actions to building and publish your docuentation automatically, so it’s always up to date. The index.html (and other files) that are built can be automatically pushed to GitHub pages.

In the root of your repository, create a .github/workflows/ folder and add the following file;

.github/workflows/build-asciidoc.yml

What does this file do? Look through the steps — checkout code, use the asciidoctor-action to build the docs directory, and then write a CNAME file so it’s got a friendly URL (docs.upsilonproject.io in this case).

Commit this to your repository, and push to Github.

Check out your new GitHub action

If all has gone well, you should get something like this;

You should notice the “build adocs” action runs with every commit. It will fail to deploy at the moment because you don’t have a Deploy Key. We’ll do that in a moment.

If you click on one of the builds, you should see AsciiDoctor running in the logs.

Create a deploy key

The official GitHub docs explain how to create a Deploy Key in detail. A deploy key is needed to authenticate GitHub actions to be able to push to your pagesbranch. Here is a brief version if you’re familiar with that kind of thing;

1. Run ssh-keygen .
2. Upload the id_rsa to a repository secret called ACTIONS_DEPLOY_KEY https://github.com/YOUR_USERNAME/YOUR_REPO/settings/secrets
3. Upload the id_rsa.pub to a repository deploy key and enable write access. https://github.com/YOUR_USERNAME/YOUR_REPO/settings/keys

Until you have created a deploy key, the action won’t work as it cannot authenticate. You might need to push a couple of dummy commits to force the GitHub action to run again and build your docs (hopefully successfully) this time!

Check our your newly hosted docs

Obviously your docs view will differ depending on your sylesheet. If all has gone well though, it should be accessible at the CNAME you created (obviously you will need a DNS record pointing to GitHub pages);

Nice!

Link to your docs

Change your repository “website” or “description” to Link to the HTML version of the docs;

Repository “about” section filled out with links to the docs.