James Read's Code, Containers & Cloud blog

Over the years I’ve used both markdown and asciidoc for writing technical documentation. Many more people are familiar with Markdown because it’s used on GitHub. However, I think I probably found AsciiDoc first because it is the standard used by Red Hat technical documentation. Both have their pros and cons, but I’ve come to realize that one is not necessarily better than the other. It really depends on the use case.

This evening finally marks the completion of the migration of https://docs.olivetin.app to a new build system, called Antora. OliveTin’s documentation consists currently of 126 AsciiDoc files, 50 images, and many example config files, code examples, and similar. I would not say it is a very large documentation site, like OpenShift or any of the Red Hat documentation that I spend a lot of time reading (also written in AsciiDoc), but it’s a decent size that has been built up over the last 3 years.