Asciidoc and Antora

Stack overview

Within the Github ecosystem, the combination of Markdown and Jekyll is a popular way to generate and host static sites. With a bit of planning and templating, it is even possible to combine multiple repositories of an organisation into a single website.

For more complex content or websites, however, it seems necessary to create bespoke tooling. Asciidoc claims to be a richer markup language, and Antora standardises how to organise multiple sources and versions.

Therefore I compared both stacks, looking at the markup languages, the organisation of sources, and some experiences.

Markup format

Table 1. Creating documentation pages
Stack Markdown Asciidoc

Markup

Format

Both have a simple text-based format that is are very suitable for version control.

Specifics

There is no single Markdown standard. Each variation adds features in their own way. [1]

It is turning into an open standard, and supposedly semantically equivalent to DITA, and offers many useful standard features. The syntax takes a bit more time to get used to.

Document meta data

Common practice is to include YAML-based "front matter" to specify meta data.

Documents have a title, followed by meta data attributes.

Document features

Markdown is deliberately limited to keep it simple. There are extensions to include the ability to work with tables or formulas.

It is possible to include CSS classes, but these will not be shown in a WYSIWYG editor.

Asciidoc supports more complex markup, such as footnotes, (nested) tables, and semantic markup, for instance for admonitions.

HTML support

Both formats allow including HTML code for further layout. In Markdown, this can be directly included. In Asciidoc, this needs to be put in a pass-thru block.

Editor support

Text editing

Most editors offer Markdown and Asciidoc plugins with a "preview" screen or tab to see the visual result. Users edit the raw text markup, with the help of syntax highlighting.

In-place WYSIWYG editors

  • Typora

  • Zettlr

n/a

Diagram support

Markdown and Asciidoc have plugins to support text-based diagram tools such as PlantUML, Mermaid etc.

Documentation site management

Table 2. Managing documentation sites
Stack Markdown/Jekyll Asciidoc/Antora

Static site generation

Main tools

There are several static site generators that support Markdown. Github uses Jekyll by default.

Antora is the main site generator for Asciidoc. There don’t seem to be many other options.

Multiple repositories and/or versions

Additional scripting and templating is needed to generating a single documentation site from multiple repositories or with multiple versions.

With Github Pages, a repository can be published as "subdirectory" of an organisation-wide site, creating a virtual single documentation site.

Antora supports multiple repositories, and adds an abstraction layer of components and versions.

Components can be re-used in different target sites. Antora changes the behaviour of some Asciidoc features to enable cross-references and improve portability.

Site design and layout

Themes and templates

There is an abundance of Jekyll templates.

Antora basically comes with a single template.

Navigation

Navigation usually depends on a mixture of document location and metadata in the document that is specific for the template or plugin used.

Navigation is based on explicit lists of cross references, and does not depend on particular metadata.

Document organisation

Structure

Jekyll has flexibility in how source documents are organised. The definition of a site is tied to the organisation of its sources.

Antora is very opiniated in how sources should be organised. The definition of a site is decoupled from these sources: it is possible to re-use content in multiple sites.

Cross references

It’s possible to use relative links, but these need to be maintained when reorganising content.

Asciidoc and Antora offer cross references that are independent of the location of documents as files.

Site deployment

Github Pages

Github Pages offers a streamlined Markdown and Jekyll by default. It is also possible to add a static site to a repository and publish it via Github Pages (without Jekyll). + With Github Actions, it is possible to use virtually any site generator in combination with Github Pages as part of a GitOps pipeline.

Specifics

Using a default Markdown and Jekyll setup is the simplest way to generate a site.

Antora can work with multiple playbooks to generate and deploy sites, but it takes more work to setup.

Experiences

Table 3. Working with these stacks
Stack Markdown/Jekyll Asciidoc/Antora

Easy of use

Writing documents

Markdown is indeed a simple format, and "real WYSIWYG" editors like Typora make writing easy.

However, as this page demonstrates, I like to work with slightly more sophistcated tables, definition lists, and more.

The Asciidoc documentation has a section title "Graduating to Asciidoc".

It offfers the features I am looking for, but also requires me to more often check with the documentation (or a preview) how to write the markup.

Publishing a site

Jekyll and Github Pages are the easiest option.

It takes some time to understand the Antora model, and decide on how to set it up for yourself.

Specifics

Github uses its own flavour of Markdown, and also limits the number of plugins that are available. It therefore takes a bit of work to seet up a local environment to "comply" with these restrictions and preview the site.

It is also possible to use a Github Action tailored to additional needs.

Antora overrides some Asciidoc behavious (such as including files outside the content source directory to document code or configuration choices, or relative paths).

Antora can work with npm extensions for Asciidoc, but not with Ruby-based extensions. This limits the number of available extensions.

As a result, regular editor plugins are not able to show complete previews.

Adapting the look and feel

Themes

There are plenty of themes to choose from. There also is a lot of information available online.

There basically is only one template, so anything other than that requires a lot of work. And apart from the Antora documentation, there is not much information availble online.

Collaboration

Documents

Markdown is the easiest format at its core. However, for proper collaboration, it would require additional agreements on the exact flavour to use, and how to work with tables, definition lists, and so on.

Smaller edits in Asciidoc are easy, but a contributor will likely need the documentation at hand for anything more elaborate. Asciidoc is being developed as markup standard, and so features are defined in the language and do not need to be standardised separately.

Organisation

The organisation of a site and the required meta data for documents also needs to be agreed and documented separately.

Antora is opiniated in its organisation of content, but it supports re-use and does not have to be standardised separately.

Alternatives

Additional options considered:

reStructuredText markup is widely used in Python environments, and also in the original IATI documentation.

Like Asciidoc, it provides more features to support technical documentation.

Since it offers fewer of such features, and does not have a site generator for multiple repositories and versions, I have skipped this for now.

Hugo is popular site generator, suitable for Markdown and Asciidoc sites, and very fast.

The Xspec project uses it.

Since it uses the folder structure of content files to determine the navigation structure, creating a single site from multiple repositories would require the same work as for a Markdown/Jekyll-based site.

Zim is a desktop notebook application that makes it very easy to keep notes and write documentation in a true WYSIWYG editor.

It supports links, tags, tasks, and a journal-style notebook. It has an export option to export a notebook as either a website or a erStructuredText version. I have also used it as my own notebook since around 2008, so it really works well for me to keep (technical) notes and pointers at hand.

However, without the application (available on Linux, with a port made for Windows), it is not really possible to contribute in editing the source. There has been discussion about adding an abstraction layer to let the application work with Asciidoc or another suitable wiki format, but until then it is not an option.

Background references

1.
Mona Bärenfänger. The Lisk Documentation migrated to AsciiDoc and Antora. 24-Feb-2020. https://lisk.io/blog/announcement/lisk-documentation-migrated-asciidoc-and-antora
2.
Horst Gutmann. Antora: Sphinx for Asciidoc. 25-Mar-2018. https://zerokspot.com/weblog/2018/03/25/antora-sphinx-for-asciidoc/
3.
Eric Holscher. Why You Shouldn’t Use “Markdown” for Documentation. 15-Mar-2016. https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
4.
Alexander Schwartz. Creating a documentation site for users with AsciiDoc and Antora. 07-Feb-2021. FOSDEM 2021, Tool the docs room. https://speakerdeck.com/ahus1/creating-a-documentation-site-for-users-with-asciidoc-and-antora-15d22d44-7228-48dc-945d-88a7c0731587
5.
Matthew Setter. Convert Markdown to AsciiDoc The Right Way! Use Kramdoc. 16-May-2019. https://matthewsetter.com/technical-documentation/asciidoc/convert-markdown-to-asciidoc-with-kramdoc/
Twitter LinkedIn Github Gitlab Meetup RSS Miro Trello Zotero Hypothesis