I've been experimenting with Asciidoc-based documentation, using Boost.Assert as my guinea pig. The good thing about Asciidoc is that Github shows a preview and you can edit it directly on github.com. This is how the source looks there: https://github.com/boostorg/assert/blob/feature/asciidoc/doc/index.adoc https://github.com/boostorg/assert/blob/feature/asciidoc/doc/assert.adoc https://github.com/boostorg/assert/blob/feature/asciidoc/doc/current_functio... This is how the generated HTML documentation looks, using the default stylesheet, without any customizations on my part: https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html And this is how the generated PDF looks: http://pdimov.com/tmp/assert.pdf The tool that produces these is Asciidoctor, http://asciidoctor.org/ .