I have now spent a decade convincing engineers and technical writers to use AsciiDoc markup for as much of their product documentation as is humanly possible. Few if any of them have regretted adding AsciiDoc to their skillset or switching to it entirely, so now I hope to make the case for a general audience.
This article collects the arguments I have long used to help writers and software developers see that AsciiDoc is far and away the optimal solution to nearly all documentation matters beyond API docs (where more structured approaches are called for).
For anyone using docs-as-code workflows and free, open-source software, the main competitor for AsciiDoc is Markdown, which many developers love and swear by. For this reason, I will compare/contrast AsciiDoc and the collective flavors of Markdown.
|
Note
|
I think reStructuredText is a solid contender in certain circumstances, such as Python developer docs. It bears all the elements of a mature tech-authoring format, but I’m afraid rST lags AsciiDoc substantially, due to clunky/peculiar syntax and highly limited tooling support. |
Not only do I think AsciiDoc is wildly superior to Markdown in nearly every way, large and small — I actually think AsciiDoc is imperative for serious, professional code-like documentation practices. If you use Markdown, you constrain your potential and risk disappointing potential collaborators who know there is a better way.
AsciiDoc is for publishing professional, rich-text tech docs; Markdown is better for notes and comments, where it is widely supported by apps and platforms.
Let’s go through the biggest advantages of AsciiDoc, followed by the main disadvantage and some related/perceived downsides.
In technical writing, when we use the term “semantics”, we do not mean there’s no real difference; it’s just semantics. We mean: the purpose of each piece of content matters, and we should convey that to readers.
Semantics-ready markup converts to semantic output, which means visual cues meaningful to most users, as well as technical cues for screen readers, search engines, and large language models (LLMs). Only a language that lets authors designate semantical formatting in the source code can hope to convey it in the rich-text output.
AsciiDoc is based on DocBook semantics, which were designed for technical writing. Markown semantics are just a back-mapping of a limited number of generic HTML elements: you get paragraphs, a subset of lists, code blocks, several handy elements for inline styling, but no real method for designating roles/classes.
The additional semantics we use in AsciiDoc technical writing are inline roles and block display formatting.
Inline roles basically translate to HTML classes on text within a sentence or line.
Both Markdown and AsciiDoc offer the basics: monospace (<code>), bold (<strong>), and italic (<em>).
AsciiDoc additionally offers #span-like# syntax, which defaults to a yellow highlighting but is really imposing a <span> tag that you can repurpose.
AsciiDoc lets you assign arbitrary (custom) roles to these different elements, so [.path]`some/path.txt` or [.keyword]*some term* or [.book]_Moby Dick_ or just [.keyword]#some term#.
All of these will convert to the appropriate HTML element and convey additional specificity of type/meaning.
When it comes to blocks, AsciiDoc again offers the basics like Markdown (literals, code listings, tables, and blockquotes).
But AsciDoc further offers:
-
example blocks
-
admonitions:
-
note
-
warning
-
tip
-
important
-
caution
-
-
sidebars
These features can make a huge difference. You won’t always use them, but when you need to, they are there, and they are standardized.
When it comes to the actual markup syntax, Markdown and AsciiDoc are very similar, as this popular comparison from Asciidoctor demonstrates.
However, where they do differ for the same task, AsciiDoc essentially always has the edge on Markdown in terms of user-friendliness.
AsciiDoc is for the most part a superset of Markdown, with some significant exceptions. This means it is truly trivial to learn to do in AsciiDoc as much as you can do in Markdown; it’s mostly the same.
To the (great) extent AsciiDoc offers more features and capability, you can learn that as needed — at least it’s available.
Here is a limited list of features that place AsciiDoc well ahead of Markdown when it comes to syntax.
-
Tables: AsciiDoc tables rule; Markdown tables are very difficult to maintain.
-
Cross-references and links: AsciiDoc’s syntax is more sensible, and its xref capabilities are a huge advantage
-
Definition Lists: AsciiDoc has them, they nest, and they’re lovely. Most Markdown flavors simply lack this essential element.
-
Italic vs bold: AsciiDoc’s markup is logical and maps to platonic standard; who can even remember which is which in Markdown (
**vs*vs__vs_)? -
Block titles: AsciiDoc supports them.
-
Ordered lists: AsciiDoc supports dynamic numbering and breaks with restarts.
I cannot think of any instances of Markdown syntax that are superior to or lack an AsciiDoc counterpart.
The only thing that comes to mind is that Markdown offers a strikethrough semantic (~~text to strike~~)… but you aren’t using strikethroughs in your technical docs… right?
This is why Markdown is sufficient (in fact designed) for notes and comments, but not professional technical documentation.
AsciiDoc does everything most flavors of Markdown can do and more. This section could be enormous, but I will stick to the most significant basics.
-
Variables: AsciiDoc supports them.
-
Conditionals: AsciiDoc supports them.
-
File transclusion: AsciiDoc offers sophisticated support.
-
Counters: AsciiDoc supports dynamic count accrual (
{counter:something}).
These are features I use regularly and honestly would not want to live without or add with hacks. This stuff should be built into any technical-writing markup and fully portable across publishing platforms.
If you are a fan of README files, you will love AsciiDoc. GitHub, GitLab, BitBucket, and other Git hosts render at least as much AsciiDoc markup as they do Markdown. This works on READMEs as well as other files, such as when rendering previews or reviews.
Better still, you can assure truly universal single sourcing of core product metadata with an AsciiDoc-formatted README. All important properties of your product can be defined as AsciiDoc attributes, which can be:
-
used as variables throughout your README and all other docs (just
includethe attributes from the README in your other docs) -
used as data to ingest into product code to establish variable properties, defaults, etc.
Imagine never getting fundamental info about and settings of your product wrong throughout your README and all your built output. Just set your key product details as AsciiDoc attributes at the top of the README, and use them everywhere from your GitHub project homepage to your backend, GUI, REST API, and all generated documentation.
Still not convinced? That’s okay, we have lots more factors that set AsciiDoc apart.
AsciiDoc is based on a consistent standard, which is now managed by a formal team under the Eclipse foundation. It’s a living, growing language that will stick to an evolving standard, rather than fracturing into “flavors” the way Markdown has.
AsciiDoc implementations (via Asciidoctor) offer a standardized means of extending and customizing how the converters work.
You can:
-
Customize the output templates, especially how HTML is rendered based on standard AsciiDoc markup cues, modifying just what you wish to alter.
-
Add functionality at numerous stages of the conversion process, manipulating document structure and more with Ruby, Javascript, or Java.
Numerous backend and frontend extensions already exist and are freely available.
Perhaps the biggest disadvantage of AsciiDoc is that once you really get into it, you risk never being okay with using Markdown or reStructuredText again, let alone anything XML-based (Word, DITA, DocBook, Flare, etc). AsciiDoc is awesome, and many people prefer to write nearly everything in it.
Sure, some people love to write in Markdown, but for actual authoring, AsciiDoc is the same or better than Markdown in pretty much every way. Its syntax is clean, it flows, and it has far fewer limitations.
While many organizations only offer documentation in HTML format on the Web, AsciiDoc also gracefully handles PDF, ePub, and Unix manpages. Even if you do not need these alternate formats now, sourcing content with AsciiDoc means having much more available, all from markup actually designed with these formats in mind instead of imposed as an afterthought.
Now to the reasons people cite against implementing AsciiDoc or for using Markdown.
There is no question that Markdown is nearly ubiquitous across modern developer platforms and tools. Nearly all tools that support AsciiDoc authoring also support Markdown, but the reverse is definitely not true.
Part of the problem is that AsciiDoc syntax conversion is only implemented in a limited number of programming languages (Ruby, Javascript, Java, and Python), and only tooling sourced in these languages can readily convert AsciiDoc without adding inconvenient dependencies. While other language ports are in development or on the way (for example, Rust), it’s far from everywhere.
|
Note
|
While Markdown conversion is implemented across many/most programming languages, very few flavors of Markdown have been ported to more than one language. Switching languages often means switching Markdown flavors, and vice versa. |
Furthermore, most REST and native API documentation generators support one flavor or another of Markdown, but not AsciiDoc. This is true of several docstring formats such as those of Doxygen, JSDoc, and DocFX, as well as the hugely popular OpenAPI Specification (OAS, formerly Swagger), which supports CommonMark Markdown.
The upside of this is that an extremely limited subset of markup is used in API documentation, such as basic inline formats, ordered and unordered lists, links, and so forth, and most of these translate well between AsciiDoc and CommonMark.
While having to switch between AsciiDoc and a Markdown flavor is not ideal, the truth is that the alternative is probably switching between multiple Markdown flavors.
In the end, most software engineering teams are using numerous “markups” between their Git hosting platform, Slack/Discord, JIRA or project-management system, and product documentation. AsciiDoc might as well be used where it is most advantageous.
Far, far, far more people know basic Markdown syntax than know advanced AsciiDoc syntax.
But as mentioned before, if you know basic Markdown syntax, you really do already know basic AsciiDoc syntax, even if you are not aware of this. To me, this is more of an upside: if you already know Markdown, you can already do that much with AsciiDoc.
While Markdown will suffice for quick and casual docs, mature technical documentation requires either:
-
extending Markdown with HTML and a templating markup like Liquid, Jinja2, Handlebars, etc (adding non-standard complexity to Markdown); OR
-
choosing a boutique flavor of Markdown that incorporates this capacity (but makes Markdown not “simple” anymore); OR
-
using standard AsciiDoc
AsciiDoc provides numerous advantages, many of them indispensable, far beyond “better syntax”. Opting for the mature and portable solution will not steer you wrong, and it signals that you opt for best practices in your documentation sourcing just the way you do with your product sourcing.