Skip to content

MkDocs vs. Antora

Before I opted to work with MkDocs, I have looked at (and worked with) other static website generator tools, like Jekyll, Hugo, and Antora.

The choice of website generator turned out to be closely tied to the choice of underlying markup language, and thereby even tied to the choice of my editor.

Comparing Jekyll and Antora

When working on an earlier assignment (around 2016-2018), we were looking at plain-text markup formats, and tools to generate websites. This is my comparison of Jekyll versus Antora back then (also based on the markup language), and on using GitHub Pages to host the documentation.

Aspect Jekyll with Markdown Antora with Asciidoc
Creating a website 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.
Themes and templates There is an abundance of Jekyll templates. There also is a lot of information available online. Antora basically comes with a single template.

Apart from the Antora documentation, there is not much information availble online.
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.
Structure Jekyll has flexibility in how source documents are organised. The definition of a site is tied to the organisation of its sources.

The organisation of a site and the required meta data for documents also needs to be agreed and documented separately.		 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.

It does support re-use, and does not have to be standardised separately.
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.
Github Pages Github Pages offers a streamlined Markdown and Jekyll by default. With Github Actions, it is possible to use virtually any site generator in combination with Github Pages as part of a GitOps pipeline.
Publishing a site 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.

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 behaviours (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.

Comparing MkDocs and Antora

In 2025, I focused on my own notes and website. Together with a preference for a Material-style layout, this changed the comparison. I basically had one option on the Markdown side: Material for Markdown. It included features like a blog, to help me replace my current website.

This led me to a new comparison, in addition to the one above.

Aspect MkDocs with Markdown Antora with Asciidoc
Creating a website There is just one option. The look and feel fits my current desires. There is just one option. The look and feel does not quite fit my current desires.
Multiple repositories and/or versions My need for support of multiple repositories or versions has mostly. disappeared.
Structure Flexibility in how source documents are organised fits well with how I manage content in Obsidian. Antora is very opiniated in how sources should be organised.
Github Pages I am publishing my own site, with local build steps. I am publishing my own site, with local build steps.
Specifics There are enough plugins to translate most of what I manage in Obsidian to an actual website (like callouts/admonitions)
Blogs The out-of-the-box features for a blog in Material for MkDocs are sufficient to replace my complete website. There are approaches to add blogs to Antora, but they are non-trivial.

Choice

With my updated needs and particular context, it seems logical to switch to a new setup with Material for MkDocs as the website generator, and Markdown as the markup language, while using Obsidian as the overal WYSIWYG content editor.

  1. Bärenfänger, M. (2020, February 24). The Lisk Documentation migrated to AsciiDoc and Antora. https://lisk.io/blog/announcement/lisk-documentation-migrated-asciidoc-and-antora
     ↩

  2. Gutmann, H. (2018, March 25). Antora: Sphinx for Asciidoc. https://zerokspot.com/weblog/2018/03/25/antora-sphinx-for-asciidoc/
     ↩

  3. Schwartz, A. (2021, February 7). Creating a documentation site for users with AsciiDoc and Antora. 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
     ↩