I use a lot of asciidoc these days for work documentation (and I love it) and I’ve been so happy that GitHub renders it when you view a repository in the web browser, just like it does for Markdown and ReStructuredText. BUT what GitHub does not do is render the image types that asciidoc does so even though I’m working with asciidoc and PlantUML, and the asciidoc tools render those diagrams nicely in PDF and HTML output – GitHub’s rendering doesn’t. So here’s a quick overview of how I handle those repositories.

Before I start, I should mention that for our context, the outputs are usually A4-sized PDF documents, so GitHub in the browser is a similar sort of form factor, and none of this stuff needs to be print quality. If you have a use case that’s none of the above, you might want to take a different approach.

Setup for GitHub AND Asciidoctor

Asciidoctor has good rendering of PlantUML (and all sorts of other format) diagrams, but GitHub does not, so the tradeoff is to have the diagram source in the repository, have build scripts (that run locally and in CI) to build the SVG version of the diagram and also include that in the repository, and to reference the SVG to include the diagram in the document.

When adding a diagram, the author creates the PlantUML (.puml) file and runs the build script which generates the SVG format in an images/ directory. The author can then put the link to the SVG file into the text.

The build script regenerates images if the user has the PlantUML tooling installed so that any update are included. If the tool isn’t there, the images/ directory is included in the repository anyway so that the content is viewable in GitHub, so the existing images can be used locally too.

Image content that works in multiple publish destinations

This version of the diagrams works perfectly well in the generated PDFs too, and since there’s a build step for PDFs there was an obvious place to hook the image generation step into.

SVG works well enough in both contexts, and while it’s annoying to have the extra build requirement for authors, I think the benefits of having the content readable with images in the repository is worth it. Having to get the published PDF to have all the information available is not great, and this is a document that has a lot more readers than writers!