Seriously, Markdown

Every so often, there’s a surge of “here’s why no one can do serious writing in Markdown” articles. They don’t come on any obvious schedule, or with any obvious trigger; usually, somebody complains about something Markdown can’t do that {reStructured Text, AsciiDoc, Org Mode, DocBook, DITA, LaTeX, Pollen, Typst, a Selectric Composer you found at a garage sale} can, it gets picked up on Hacker News, and a few hundred nerds chime in to explain it’s because Markdown {has no formal specification, isn’t extensible, was just designed for blog posts, ran over their childhood dog}.

When this happens, I look over from the technical writing I’m doing in Markdown, or possibly the next novel I’m writing with it, and nod thoughtfully. I should, I presume, prepare my resignation letter now, apologizing for not being a serious technical writer, while gently explaining to my current and past clients and employers the error of their ways. Yes, the same people on Hacker News a decade ago were holding up RethinkDB’s documentation as terrific, but if they only knew I’d been writing in Markdown, it would suddenly become unserious. The entire Microsoft Learning Portal? Away with it! And folks I haven’t worked with better be informed, too. Yes, Stripe’s docs are considered a gold standard, but they are written in Markdown! Get the Shame Nun in here, stat!

All right, let’s be slightly more serious. Yes, there are countless different Markdown processors out there, and yes, all of them handle edge cases differently. But where they “fail” 99% of the time are edge cases, and if you follow reasonably good practices—the sort of nitpicky things that MarkdownLint whines about—you’re pretty unlikely to run into trouble. I’ve been doing this for a long time, and I’ve never had to learn a “new” style of Markdown or unlearn bad habits from previous work.

I know I can’t speak for everyone’s experience. But if you write Markdown like this on the regular:

# My Great Document
Who needs blank lines after headings; this works
_most_ of the time!

This next line will surely become the horizontal rule 
tag I intend.
-----

- Bullet 1
- Bullet 2
- Bullet 3, which is not connected to the link below 
despite the lack of spacing
[A [cool website](http://bar.com)](http://foo.com)!

I'd really like to **emphasize *this and also** this*
right now.

And somehow you get away with it until you switch Markdown processors, I’m sorry, but the processor is not the issue. If you write crappy Org Mode markup, you’re going to get crappy Org Mode output.

“Yes, but it’ll be the same crappy output no matter the processor! That’s the problem!” Yeah, but is it? Most other lightweight markup systems only have one or two implementations. If you’re using Org Mode, you are almost certainly using the actual Org Mode in Emacs; if you’re using AsciiDoc, you’re probably using AsciiDoctor to process it. AsciiDoc’s formal specification is still a work in progress, and there’s no formal spec for Org Mode’s markup, as far as I can tell. If there were only one or two Markdown processors out there, this probably wouldn’t be an ongoing debate.

Here’s my theory: what’s at the root of these complaints is that people want Markdown to be something it isn’t. It’s a markup syntax that represents a subset of commonly-used HTML. You can plug it into a content management system or a static site generator, but it isn’t a CMS or an SSG any more than HTML itself is. AsciiDoc and reStructured Text, on the other hand, are markup languages closely tied to specific documentation generators, AsciiDoctor and Sphinx. Org Mode is a plain-text structured editing system for outlining, task and agenda management, literate programming, and publishing to multiple output formats. They’re complete solutions for specific problems. If you have that specific problem and you want a complete solution, you don’t want Markdown.

So: why do all these companies use it anyway? Why is your favorite documentation so likely to be written with Markdown behind the scenes?

Well, I’m going to go out on a limb here: it’s because it’s a markup syntax that represents a subset of commonly-used HTML, rather than a complete solution.

Markdown doesn’t care what content management system you’re using, or if you’re using one at all. How your site is constructed, whether you’re using a template system or a CSS preprocessor or crazy-ass client-side rendering, is not in Markdown’s domain. Use the CMS you’re already using—there’s probably a plug-in. Need extensibility? That’s your site generator’s issue. Write your own damn shortcodes.

“Wait,” somebody’s surely saying. “How is that an advantage?” It’s an advantage because you have all of HTML and CSS at your disposal. If you know how to use them, you get exactly what you want, full stop. That’s not a goal of AsciiDoc or reStructured Text or Org Mode, or much of anything else I’ve seen proposed as better alternatives. (It is a goal of Dean Allen’s nearly forgotten Markdown predecessor, Textile, but like Markdown, Textile isn’t in and of itself a site generator.) I’m not positive that, say, Stripe’s documentation site couldn’t be reproduced in rST, but I think it’d be really damn hard, and a lot of that has nothing to do with the capability of the markup system. It has to do with the flexibility of the output.

To be sure, you can integrate non-Markdown markup into another system. GitHub renders README files with a variety of lightweight markup styles; some SSGs and CMSs have plugins that let them process rST or Org markup or what have you; you can always set up a workflow that lets you export from your favorite format to HTML or (ahem) Markdown transparently. That’s great if you’re more familiar with another markup style and want to keep using it, but that’s not an argument for superiority, it’s an argument for familiarity. When you focus purely on the markup semantics, it’s hard to argue that any other system is “better” than Markdown. (I find text that uses Markdown markup to generally be more readable in its unprocessed form than most other lightweight systems, and that’s important to me, but it may not be important to everyone.)

I’m not saying “give up and just use Markdown.” Being familiar with another markup system is a powerful argument for staying with it, for a start, and there are other reasons to use something else that have nothing to do with markup. There are specific kinds of technical documentation—usually in contexts where a lot of sections are shared between manuals, revised independently, and assembled programmatically—where AsciiDoc is your only practical alternative to full-bore SGML/XML. And as a newly anointed Emacs nerd, I find myself using Org Mode daily at work, and that includes writing extensive notes using its markup system, not Markdown. I’m using it primarily for its task management capabilities, though, because that’s the kind of stuff Org was designed for.

But you know what else Emacs is excellent at editing? The lightweight markup I’m actually using when I write developer documentation for one of the most popular games in the world, published by one of the biggest software companies in the world? Here’s a hint: not reStructured Text.