No markup is magical

Corrections

Someone corrected me that reStructuredText is used with more than just the Sphinx framework, such as the tools/frameworks Nikola, rhinotype, or Pelican. I would still say its adoption is limited compared to Markdown, but not to a single platform.

2023 saw me start a technical writing job in which I had to use the AsciiDoc markup language. A year later, I was leading a migration to a documentation platform that used Markdown, despite AsciiDoc being a much more “complete” language.

After a while of using Markdown, I’ve mellowed out on how I see markup languages.

Background

When I think of markup languages in technical writing, I think of the “big three”: Markdown, AsciiDoc, and reStructuredText. All three are plain-text markup languages that integrate with documentation platforms.

Markdown is the simplest of the three languages, based on formatting conventions from email and Usenet. It’s simple. It’s fast to parse. Its formatting can be ambiguous. It has been extended to various flavors and derivatives. It has a lot of tools available in multiple programming languages.

AsciiDoc is a bit older than Markdown, and is the plain-text version of the DocBook markup language. It looks a bit like Markdown. It has many more features. Its reference tool is in Ruby, and is opinionated about output styles. It has its fans, but has much lower adoption.

reStructuredText, or rST, is a markup language for the Sphinx documentation platform. It’s based on Python syntax. It has a reputation of being powerful. Its syntax seems esoteric compared to the other two. It’s only available for a single documentation platform, but that one platform has significant mind share.

After posting this, someone corrected me

These descriptions are not comprehensive, but they’re a start.

The debate

If you hang around technical writers, you will eventually hear about the merits and flaws of each markup language.

You may come across discussions about how Markdown doesn’t have enough features for serious documentation (and likely due to poor table support). In the same discussion, someone will chime in about how AsciiDoc is far superior, far more complete, and you should use it if you’re really serious. You may hear about rST, but I get the impression that rST is in more of a if you know, you know kind of situation; I see less talk about it, but nobody disagrees that it is powerful.

It’s true that Markdown is simple. From a feature standpoint, it’s objectively inferior: anything you can do in Markdown you can do in another language. However, it doesn’t support as many features as the others, such as powerful tables, variables, or callouts. Markdown had to be extended to gain a features, and one of the most common flavors is MDX… which is powerful because you extend it with JavaScript-like features! That goes from simple to incredibly complex.

However, lots of tools and documentation sites keep using Markdown. You can talk about its limitations, but it’s hard to deny that Markdown is easy to learn, easy to tool, and sufficient for most things that people actually do.

The other markup languages aren’t without their faults either.

rST’s big limitation is how it is tied to a single documentation platform which, while powerful, still deprives you of choice. Sphinx has a very good reputation, so the choice isn’t necessarily a bad one, but it’s still just one. Better hope it either has a theme you like, or you had better find a web developer!

AsciiDoc, for me, is also in a weird middle ground between the other two. While it’s not officially tied to a single platform, there is only one documentation platform with first-class support for AsciiDoc: Antora, made by the same team. The other platforms that support AsciiDoc often only support it with unofficial plugins that tend to have quirks. Despite having used Antora, I believe it needs some work.¹ Oh, and the AsciiDoc tools tend to be slower (at least as far as I’ve seen).

My take

I don’t think any of the three markup languages are truly awful, depending on the context. They all have their advantages and disadvantages.

AsciiDoc and rST are powerful. They have significant limitations related to their ecosystem and tooling, but you can definitely make complex documentation with them. I mean, there’s a reason people like them!

Markdown and its flavors are simple, but you know what? I’m finding that useful in a web design context. A lot of documentation lives online; technical writers end up being bona fide web designers due to the complexity of writing documents that can be easily read on multiple devices. When I’m creating a documentation page, complex syntax may not flow and reflow well, so those complex tables other people love wouldn’t work well anyhow!

I guess I’ve mellowed out because I don’t see any markup language as entirely enough. I would much rather write plain text, take out a magic wand, and magically arrange the text into the best way to present it.

There is no magic. There are only tools we have to pick based on the context and the information we have, and all options seem easier than going back to writing plain HTML. I would pick any of the three languages over writing HTML.

In most cases, anyhow.