We live in the era of everything-as-code. Documentation most certainly is part of that. Asciidoc is something I really enjoy. It’s nice and easy and if you need really fancy stuff, you can do that as well. However, what sometimes is a bit challenging, is to have a setup which doesn’t break. Just recently it broke, beacuse vagrant required a different version of rubygems than the ones which got installed via RPMs. This also affected asciidoc. Wouldn’t it be nice, if there was a somewhat independent way of being able to generate your docs? Lucky for us, we also live in an era, where we have containers. So, on my Fedora box, all I needed is just podman, a Dockerfile and in my case also some fonts where no alpine package exists yet which I could just install.

The Dockerfile is fairly simple:

  1. Take the official asciidoctor-docker image as base image
  2. add your fonts (if you need)
  3. update the font cache (if you added your own fonts)

So, in my case it looks like this:

FROM asciidoctor/docker-asciidoctor

RUN mkdir /usr/share/fonts/redhat
RUN apk add --no-cache ttf-liberation
COPY redhat-fonts/TTF/* /usr/share/fonts/redhat/
RUN fc-cache -f -v

In my case I wanted to use the Red Hat fonts. And because the style I am using, Liberation is also in the mix. Since there is no alpine package, I just used a git submodule in the repo which pulls the fonts directly from the respective github repo. There are more ways of doing that, but this really is up to your use case.

Then just build the container image and use it :)