Asciidoc: When Markdown Just Isn't Cutting It

I taught myself HTML a long time ago, on a software called HotDog (Pro?). There wasn't such a thing as What You See Is What You Get capabilities at the time. However, HotDog had an amazing feature: the toolbar had all HTML tags (there weren't that many at the time) as buttons, and you could learn them by clicking on them and watching the results. The only downside was that you had to click on another button to close the tag.

\ Then came Dreamweaver. It was the first WYSIWYG editor, and it immediately became very popular. People who had no clue about HTML started to use it: the number of websites skyrocketed. I used it once and looked at the generated HTML. Having learned to write HTML "by hand", I found it generated by Dreamweaver overtly verbose. I continued to write my HTML by hand or with the help of IDEs.

\ Fast forward fifteen years. HTML went beyond websites to be an ubiquitous format that Sir Berners-Lee wouldn't have dreamed it would become. Coupled with web browsers, it went on to become the medium for web applications. Yet, it didn't stop there. Even at the time, I was amazed that JavaDocs generated HTML. Python docstring? Generates HTML. Ruby rdoc? Generates HTML. Rust rustdoc? Generates HTML.

\ While you can write HTML snippets, e.g., in JavaDocs, writing HTML by the line becomes a bore quite fast. It's easy to miss a slash in the closing tag, or to get a <table> right on the first attempt, especially if it involves spans. Yet, most documentation doesn't need the full power of HTML, especially the kind brought by its more modern versions.

\ To address this issue, John Gruber and Aaron Swartz invented Markdown in 2004.

\ Markdown took the world by storm. I think that it's even more popular than HTML, at least in the tech world. It's been available on GitHub for ages. Java integrated it into its JavaDocs in version 25. And nowadays, LLMs use Markdown for input and output!

Markdown Limitations

Markdown is amazing, but it has strong limitations. I wrote my latest book with Markdown, in the Doc-as-Code tradition. The experience was so painful that I vowed never to do it again.

\ Here's a simple excerpt from my book-writing experience. I wanted to feature code snippets to illustrate my points. However, I wanted them to be valid: compiled and tested. I wrote a project, complete with a build configuration.

\ Yet, Markdown doesn't allow the inclusion of external files. I had to copy and paste the required snippets. Worse, because writing a book takes some time, I kept the version of the dependencies up-to-date. Each time I did, I had to copy-paste the updated code at every occurrence. Interestingly enough, documentation aimed at developers has the same use case.

\ Another widespread limitation is wanting to draw attention to an item. Here's a styling option:

Markdown doesn't offer anything similar. For this reason, Python Markdown does. What about other languages? I don't know; I wish it were part of Markdown.

\ Though there are many more, my final point will be about tables. Markdown handles tables, up to a point, which is column headers. In my blog posts, I regularly need rowspan and colspan, which aren't supported. Fortunately, HTML is valid Markdown. However, the formatting inside the table, code, etc., must be transformed into HTML along with it.

Asciidoc

Asciidoc is the solution to the above limitations.

\ Let's see how Asciidoc addresses limitations one by one:

• Include:

\

• Admonitions:

\

• Cell span

  Asciidoc has a specification as well as a TCK, both managed by the Eclipse Foundation. Note, though, that Asciidoctor is the sole implementation of Asciidoc. The Asciidoctor site is actually hosting the Asciidoc documentation. For most intents and purposes, you can treat them as one, as I do.

  \

I listed above how Asciidoc solves three limitations I regularly encounter in Markdown, but it provides many more benefits. Tons of features are available. Here are a couple of them, which I use regularly:

• Video embedding:

  A sample is more descriptive than a complete description:

[source] ---- video::RX9zwgHuNmA[youtube,width=840,height=473] ----

• Blockquotes with attribution, as seen above:

[quote,'https://asciidoc.org/[Asciidoc^]'] ____ AsciiDoc is a plain text markup language for writing technical content. ____

• Collapsible blocks. This one is of utmost importance when I write self-driven workshops:

[%collapsible] ==== This content is only revealed when the user clicks the block title. ====

• Materializing menus and buttons is another useful feature for workshops and technical documentation in general:

• Click on the OK button.

• Go to the Text > Text Filters > JSON item.

  \

• Automatic table of contents

With the right toolchain, you can generate HTML from Asciidoc and publish the result on GitHub/GitLab Pages. Here's a non-trivial example that showcases several features:

Apache APISIX Hands-on Lab

Asciidoc Ecosystem

A tool is only as useful as its surrounding ecosystem. Here are a couple of such tools and benefits:

• GitHub renders Asciidoc as well as Markdown. Try using a README.adoc and watch the magic happen. Here's a non-exhaustive list of Asciidoc integration items with GitHub.
• Jekyll, the blog engine, has a seamless Asciidoc integration. This blog runs on Jekyll with Asciidoc.
• Asciidoctor Diagram:

I use it a lot with PlantUML. You might have noticed it on this blog already.

• Reveal.js integration:

  Asciidoc allows you to generate regular HTML documents, but Reveal.js enables the creation of slide-based presentations. When I taught at university, I used both regular HTML for seminar works and slides for courses. My old Java EE course is available as a GitHub Pages site (in French).

  \ Icing on the cake, you can leverage the diagram integration.

Conclusion

Markdown is everywhere, and I'm more than happy if it meets your needs. I had several experiences where it didn't meet my expectations: technical documentation, workshops, courses, and book writing. Asciidoc is the perfect tool to fill Markdown's gaps.

\ I hope this post gave you enough arguments to try it.

To go further:

• Asciidoctor Documentation
• Asciidoctor reveal.js
• Asciidoctor Diagram
• Jekyll AsciiDoc Plugin

Originally published at A Java Geek on October 26th, 2025