Why Use Asciidoctor Over Markdown?

Markdown is a great lightweight markup language, but for technical documentation, Asciidoctor offers a more powerful and flexible alternative. In this post, we’ll explore the reasons to choose Asciidoctor, focusing on its extended capabilities, structured approach, and customization options.

Understanding AsciiDoc vs. Asciidoctor

Before diving deeper, it’s important to clarify the difference between AsciiDoc and Asciidoctor:

  • AsciiDoc (.adoc): A lightweight markup language designed for structured documentation, similar to Markdown but with more advanced features.
  • Asciidoctor: A fast and feature-rich implementation of the AsciiDoc language, written in Ruby. It enhances processing speed and provides additional capabilities like macros, built-in styling, and multi-format output.

Asciidoctor is to AsciiDoc what a Markdown processor (like Pandoc) is to Markdown—it takes raw .adoc files and transforms them into various formats efficiently.

The Power of Asciidoctor

Asciidoctor extends the functionality of AsciiDoc, making it an ideal choice for structured technical writing. Unlike Markdown, which often requires additional tools to achieve similar results, Asciidoctor offers:

  • Rich Semantic Structuring: Unlike Markdown’s simple headings and lists, Asciidoctor provides semantic elements like sidebars, admonitions, footnotes, and tables of contents.
  • Built-in Customization: Easily configure document attributes, styling, and output formats.
  • Multi-Format Output: Convert content into HTML, PDF, EPUB, and even slides without external dependencies.
  • Advanced Cross-Referencing: Define anchors and references within documents, something Markdown struggles with without extensions.
  • Automation & Processing: Use attributes and macros to dynamically insert content, images, or metadata.

Organizing Individual Files

A key advantage of Asciidoctor is its ability to modularize documentation. Instead of writing everything in one large file, I write individual files for each topic and then pull them into a main section file. This approach allows for:

  • Better organization: Each file remains manageable and focused.
  • Reusability: Sections can be reused in different documents.
  • Simplified collaboration: Multiple contributors can work on different sections independently.

A typical main file structure could look like this:

<<<
include::02_how_to_read_doc.adoc[]

* * *
// Forces blank line after horizontal rule
image::{end-section}[width=3%, align="center"]

<<<
include::03_commands.adoc[]

* * *
//
image::{end-section}[width=3%, align="center"]

<<<
include::13_version_control.adoc[]

Each include:: statement pulls in an individual file, making it easy to assemble a final document, reuse files elsewhere - and generally aligns with certain practices of programming such as DRY (if a section needs to be repeated it can be updated in one location); Separation of Concerns (files focus on a specific topc, making it easier to manage and maintain without affecting unrelated sections); Single responsibility principle - each module should have only one reason to change.

Custom Table of Contents (ToC)

Another feature I’ve implemented is a customized table of contents. Instead of using the default Asciidoctor ToC, I designed a ToC that functions similarly to a sprite, keeping navigation visually clean while retaining all necessary linking capabilities.

Configuration for my custom ToC looks like this:

:toc: left
:toclevels: 0
:toc-title: Table of Contents
:docinfo: shared

Implementing Tocbot for Dynamic Navigation

In addition to a static ToC, I also use Tocbot, a JavaScript library for generating dynamic table of contents based on page structure.

To integrate Tocbot, I found the details in this StackOverflow discussion usefulTocbot StackOverflow

Benefits of Tocbot

  • Automatically updates when new headings are added.
  • Responsive adjustments based on screen width.
  • Collapsible structure for deeper heading levels.

Making a Custom Stylesheet

You can override Asciidoctor’s default styling with a custom stylesheet:

body {
    font-family: "Inter", sans-serif;
    background-color: #f8f8f8;
}

h1 {
    color: #333;
}

The default styles are documented in detail at: https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/

Conclusion

If you’re writing technical documentation, especially for books, guides, or detailed reference material, Asciidoctor is a solid choice. Its extensibility, structure, and multi-format output make it a better tool than Markdown for many use cases. While Markdown remains the easiest choice for simple notes and blogs, Asciidoctor is worth considering when you need more control over formatting, styling, and automation.