The Eternal Truth of Markdown

Markdown became a core part of how I wrote. The simplicity and flexibility meant I would live the dream of write once, run anywhere. It did lead to some ambiguity, though. Gruber would probably say this is by design. His emphasis throughout the Markdown documentation is on the syntax of Markdown, not—say—the resulting HTML. His Perl script does not support HTML class names or IDs, for example, so you can’t add those to the generated HTML. By the logic of the original Markdown script, if you want complete control over the HTML output, then you’d need to write in HTML.

This situation is great for Markdown users: that is, writers. It’s less great for programmers. In fact, it drives them crazy. Programmers do not like ambiguity. It goes against so much of what programming is about. As a writer using Markdown, I love that I can pick whichever particular version is best suited to my needs. As a programmer, I hate that when I build something I have to make this same decision, which then affects all the people who use my finished product. Maybe I didn’t support some specific extension they were expecting because they’ve always used the same Markdown parser and assume that feature is available.

If this weren’t bad enough, there are also some ambiguities in the syntax. For example, asterisks are used for italics when singular (*like this*) and bold when doubled (**like this**). So far so good. But what should happen if you write **like* this**? Should that be rendered like* this? Or maybe like this*? There’s no way to know; whoever is writing the parser has to make that decision.

What’s more, unlike most extremely successful pieces of code, Markdown is not publicly hosted on the code-sharing site du jour. It doesn’t have hundreds of people contributing to it, and the last time the original Perl script was updated was 2004. This too rubs programmers the wrong way. We’re a cliquish bunch; things outside the clique are viewed with suspicion.

About a decade ago, there was an effort to eliminate the ambiguities in Markdown and bring it into line with coding dogma. Some programmers got together and created CommonMark, which makes the choices the original Markdown script doesn’t and came up with what its creators think is the One Right Way to Do It.

CommonMark offered comfort. It’s on Github. It has a discussion forum. It seems to be an active project. I have never personally incorporated CommonMark into a project, but its parsers are what convert your Markdown to HTML on such popular sites as Stack Overflow, Github, and Reddit. (To eliminate the asterisk ambiguity, for example, it proposed underscore for italics, asterisk for bold.) Presumably the developers behind CommonMark consider it a success.

But it’s not Markdown. Not in name, and I would argue not in spirit.

Around the time the CommonMark effort was happening, the software developer Dave Winer told me something I still think about: Markdown belongs to everyone who uses it. This is literally true because of the license. But it also reminded me of the real point of free software. We all have a say in it: by using it, by adapting it, even by forking it.

Whether Gruber intended it this way or not, Markdown does belong to everyone, and there is no standard. I use a very old version of Markdown for Python. Gruber presumably still uses his Perl script. Other people use other versions. It’s messy. It’s ambiguous. It’s human.

And this, in the end, is the Way.