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. Python docstring Ruby rdoc Rust rustdoc 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. e.g. <table> To address this issue, John Gruber and Aaron Swartz invented Markdown in 2004. Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language.
-- Markdown Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as an easy-to-read markup language. -- Markdown Markdown 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. Python 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. rowspan colspan Asciidoc Asciidoc is the solution to the above limitations. AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.
-- Asciidoc AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats. -- Asciidoc Asciidoc Let's see how Asciidoc addresses limitations one by one: Include:

An include directive imports content from a separate file or URL into the content of the current document. When the current document is processed, the include directive syntax is replaced by the contents of the include file. Think of the include directive like a file expander.



Admonitions:

There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. This page introduces you to admonition types AsciiDoc provides, how to add admonitions to your document, and how to enhance them using icons or emoji.



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. Include:

An include directive imports content from a separate file or URL into the content of the current document. When the current document is processed, the include directive syntax is replaced by the contents of the include file. Think of the include directive like a file expander. Include: Include An include directive imports content from a separate file or URL into the content of the current document. When the current document is processed, the include directive syntax is replaced by the contents of the include file. Think of the include directive like a file expander. An include directive imports content from a separate file or URL into the content of the current document. When the current document is processed, the include directive syntax is replaced by the contents of the include file. Think of the include directive like a file expander. Admonitions:

There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. This page introduces you to admonition types AsciiDoc provides, how to add admonitions to your document, and how to enhance them using icons or emoji. Admonitions: Admonitions There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. This page introduces you to admonition types AsciiDoc provides, how to add admonitions to your document, and how to enhance them using icons or emoji. There are certain statements you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. This page introduces you to admonition types AsciiDoc provides, how to add admonitions to your document, and how to enhance them using icons or emoji. 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. Cell span 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. specification TCK Asciidoctor Asciidoc documentation 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 Video embedding:
A sample is more descriptive than a complete description:
[source]
----
video::RX9zwgHuNmA[youtube,width=840,height=473]
---- Video embedding: Video embedding A sample is more descriptive than a complete description: [source]
----
video::RX9zwgHuNmA[youtube,width=840,height=473]
---- [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.
____ Blockquotes with attribution, as seen above: Blockquotes with attribution [quote,'https://asciidoc.org/[Asciidoc^]']
____
AsciiDoc is a plain text markup language for writing technical content.
____ [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.
==== Collapsible blocks. This one is of utmost importance when I write self-driven workshops: Collapsible blocks [%collapsible]
====
This content is only revealed when the user clicks the block title.
==== [%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. Materializing menus and buttons is another useful feature for workshops and technical documentation in general: menus and buttons Click on the OK button.


Go to the Text > Text Filters > JSON item. Click on the OK button. Click on the OK button. Go to the Text > Text Filters > JSON item. Go to the Text > Text Filters > JSON item. Text > Text Filters > JSON Automatic table of contents Automatic table of contents 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 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:

Asciidoctor Diagram is a set of Asciidoctor extensions that enable rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process.

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. 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. 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. README.adoc magic happen Asciidoc integration items with GitHub Jekyll, the blog engine, has a seamless Asciidoc integration. This blog runs on Jekyll with Asciidoc. Jekyll, the blog engine, has a seamless Asciidoc integration. This blog runs on Jekyll with Asciidoc. Asciidoc integration Asciidoctor Diagram:

Asciidoctor Diagram is a set of Asciidoctor extensions that enable rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process.

I use it a lot with PlantUML. You might have noticed it on this blog already. Asciidoctor Diagram: Asciidoctor Diagram Asciidoctor Diagram is a set of Asciidoctor extensions that enable rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process. Asciidoctor Diagram is a set of Asciidoctor extensions that enable rendering of plain text diagrams that are embedded in your AsciiDoc document as part of the Asciidoctor conversion process. I use it a lot with PlantUML. You might have noticed it on this blog already. a lot 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. Reveal.js integration: 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). Java EE course Icing on the cake, you can leverage the diagram integration. 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: To go further: Asciidoctor Documentation
Asciidoctor reveal.js
Asciidoctor Diagram
Jekyll AsciiDoc Plugin Asciidoctor Documentation Asciidoctor Documentation Asciidoctor reveal.js Asciidoctor reveal.js Asciidoctor Diagram Asciidoctor Diagram Jekyll AsciiDoc Plugin Jekyll AsciiDoc Plugin Originally published at A Java Geek on October 26th, 2025 Originally published at A Java Geek on October 26th, 2025 A Java Geek

Apache

Testing the Untestable: A Simple Way to Handle Static Methods in Legacy Java

Read all my posts!

Asciidoc: When Markdown Just Isn't Cutting It

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

16 Best Practices For Securing Your APIs with Apache APISIX - Part 1

Publishing our Asciidoc Developer Guide as a Book on Amazon

10 Knowledge Base Software Best Practice Examples

5 reasons to ditch the paper and start document automation

5 Software Documentation Tools That Make Managing Technical Documentation Easier

16 Best Practices For Securing Your APIs with Apache APISIX - Part 1

Publishing our Asciidoc Developer Guide as a Book on Amazon

10 Knowledge Base Software Best Practice Examples

5 reasons to ditch the paper and start document automation

5 Software Documentation Tools That Make Managing Technical Documentation Easier

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps