In the meantime, a company I know has noticed that it has also encountered the problem described here. After all, any kid can use Word, right? As much as I would love to utter sentences like “I told you so.” in these moments, I also like to offer my help in such situations. For this reason, one of the documents that are regularly updated and versioned and made available to third parties will now be switched to AsciiDoc as a test. At the same time git will be introduced for change tracking and versioning, but that’s another challenge I might write about some other time.

I must admit that I was also pleased about this task. So I finally had a reason to deal with AsciiDoc in more detail and could push the unfortunately already neglected pet projects even further back. I have to say that my first positive impression about AsciiDoc has only been strengthened. Since it is important for the company to have a PDF in the corporate design at the end, I was glad to have come across Asciidoctor PDF, which generates PDFs directly from AsciiDoc. I never liked the “detour” with DocBook as an intermediate format when generating the PDF, especially because I know how time-consuming such design adjustments can sometimes be with DocBook.

Asciidoctor PDF is written entirely in Ruby and is also easily installable on Windows systems. All possible design customizations of Asciidoctor PDF are documented in the Theming-Guide and are then configured in a YAML file.

!!! warning “Warning” To avoid problems with non-ASCII characters (e.g. umlauts) it is important that the command line used to invoke Asciidoctor PDF is encoded with UTF-8. This should be the case directly under Linux, but under Windows the command chcp 65001 must be executed beforehand for this.

One point that also gave me a headache for some time is the lack of configurability of the cover page. In many places, one stumbles across the most diverse requirements for a cover sheet, which cannot be fulfilled at first. But for every problem there is a solution and also in this case I found a solution that I like very much. In AsciiDoc you can use the option :front-cover-image: to include an image that is rendered directly behind the cover page. Combining this with the :notitle: option, which prevents the actual cover page from being rendered, results in a customized cover page. The “front cover image” is simply a PDF that I created with LibreOffice Writer.

But I also have to disagree with myself on one point. I touted AsciiDocFx as an editor at the time, but have since come to the decision that Visual Studio Code paired with the plugins from asciidoctor is the better editor.