Markdown is a great thing; but nothing beats Asciidoc for complex documentation projects.
I discovered Asciidoc while writing the books I published at O’Reilly. Back in 2012 they had an astonishing publishing pipeline built around it, following an early form of “GitOps”. Or, rather, “SubversionOps”: commit your changes to the Subversion repository, and a few minutes later download a fully formatted PDF file, including all the fonts, looking exactly as the real thing.
Until around a decade ago though, Asciidoc had a bit of a problem: the only available implementation back then was an aging project built in Python somewhere in the 2000s, and it seemed kind of stuck. Dan Allen thought the same, and started a major undertaking: thus was born the Asciidoctor project.
Nowadays, Asciidoctor is a beast of a project, with implementations in Ruby and JavaScript, including extensions for EPUB and PDF generation, diagramming, support for source code and tables, mathematics, presentation slides, user interface macros for menu entries and buttons, and much, much more. It is a serious contender to the title of the most awesome technical documentation tool ever created.
Asciidoctor is more suitable for large documentation projects thanks to the include directive, allowing large documents to be split in smaller ones; a painfully missed option in Markdown, in my opinion, which is an otherwise brilliant and ubiquitous format.
And if all of that was not enough, Asciidoctor begat Antora, a complete website generator with all the bells and whistles one would expect in 2020.
(Actually, Antora is not the only website generator that supports Asciidoc; Hugo does it off-the-box as well.)
Antora has a few features that set it completely apart in its market:
- Complete separation from content and form; we have created various different Antora themes, for example for VSHN, Project Syn, and APPUiO, and we can choose any of these for our websites. We even have a Cookiecutter that offers users the choice of which theme to use when creating a new Antora project.
- The ability to fetch and coalesce documentation sets from various different websites, generating a single website with all of that documentation put together. This is how we created the Project Syn documentation, merging the docs from its different components: Commodore, Lieutenant API and more.
Being a static site generator, Antora does not provide a built-in search engine system; fear not, we have developed our own embedded search engine with its dedicated indexer, all collaborating together nicely in our GitLab CI/CD pipeline.
Not only that! We have created an Antora Preview container image, used by documentation authors to make preview their docs on a browser in real time.
I plead guilty, your honor, and without regrets I affirm I am one of the principal instigators of the introduction of Asciidoctor and Antora at VSHN, in all of its forms. At this moment we are actively using it to generate documentation websites such as the Handbook, the Knowledge Base, and the Project Syn documentation. We use it also to create presentation slides ready to be deployed in APPUiO, our container platform based on OpenShift.
Thanks to Asciidoctor’s JavaScript API we even built a document generation application, where we use Asciidoc templates to generate PDF, Word, and LibreOffice documents, integrating the whole thing into SignRequest, speeding up the work of our sales team. This app is one of our secret weapons to serve our customers better.
The choice of an open standard such as Asciidoc, with a lively and powerful implementation such as Asciidoctor, in turn powering a documentation workhorse such as Antora, has transformed our documentation workflow and keeps on offering new possibilities. I can heartily recommend them all.