How to Create a Dev Container for Asciidoctor

We use AsciiDoc as the format for our documentation for the user group project. AsciiDoc is a bit like Markdown, but it supports multi-file documents out of the box and without any quirks.

We use the Ruby app Asciidoctor to turn our AsciiDoc files into a PDF as part of our build job. Since building the whole application takes time, it is not the fastest way to get feedback when we write the documentation. To shorten the feedback cycle, we put Asciidoctor into a development container to create the PDF whenever we want to check something.

 

Create a Gem file

In the Ruby Gemfile, we can put all the packages we need to generate our documentation:

 

Create a Dockerfile

For the Dockerfile we used the template I documented in this post on dev containers for Ruby apps. We use the newer Debian release and do not care much about specific versions of Ruby or Bundler:

 

Create a Docker Compose file

The configuration for Docker Compose may be a bit overhead, but it allows us to set the path for our volume correctly and now is everything in place should we need to add another container.

 

Start the container

We can now start our dev container with this command:

From time to time, you should rebuild your container to run apt-get update with this command:

 

Generate the documentation

We can now open a Terminal inside Docker for Windows and run this command inside our container:

This generates us the PDF file and we can use the Windows Explorer (outside of the container) to check if the PDF file is correct. To not always type this command, we put that into a CreateDocumentation.sh file.

 

Conclusion

With the help of our new development container, we can run Asciidoctor without the need to install Ruby or wait on the build agent. This allows us a much faster feedback cycle in which we can keep the momentum to write our documentation.

I did not expect that the faster cycle would make much difference but let me tell you that it is like day and night. Therefore, I can strongly advise you to take that hour it took me to build the container with all the right dependencies and automate that part of your workflow – it is worth it.