Markdown has become a core part of my writing. The simplicity and flexibility meant I fulfilled the dream of writing once and running anywhere. However, this led to some confusion. Gruber would probably say this is by design. Throughout Markdown documentation, the emphasis is on the Markdown syntax rather than, say, the resulting HTML code. His Perl script doesn’t support class names or HTML IDs, for example, so they can’t be added to the generated HTML. Following the logic of the original Markdown script, if you want full control over the HTML output, you must write in HTML.
This situation is great for Markdown users, i.e. writers. This is less beneficial for developers. In fact, it drives them crazy. Programmers don’t like ambiguity. This goes against many programming principles. As a writer who uses Markdown, I love that I can choose the version that best suits my needs. As a developer, I hate that when I build something, I have to make the same decision, which then affects all the people who apply my finished product. Perhaps I didn’t support some particular extension they expected because they always used the same Markdown parser and assumed that feature was available.
As if that wasn’t enough, there are also some syntax ambiguities. For example, asterisks are used for italics in the singular (*this way*) and bold for the dual (**this way**). So far so good. But what should happen if you write **like* this**? Should this be rendered I like this? Or maybe I like this*? There is no way to know this; whoever writes the parser has to make this decision.
Moreover, unlike most wildly successful pieces of code, Markdown is not publicly hosted on the code-swapping site du jour. They don’t involve hundreds of people, and the last update to the original Perl script was in 2004. This also confuses developers. We are a tight-knit group; things outside the clique are viewed with suspicion.
About a decade ago, an attempt was made to eliminate the ambiguities in Markdown and bring it in line with coding dogma. Some developers got together and created Common Markthat makes choices that the original Markdown script doesn’t, and has come up with what its creators believe is the only right way to do it.
CommonMark provided comfort. It’s on Github. It has a discussion forum. This appears to be an lively project. I’ve never personally incorporated CommonMark into a project, but its parsers convert your Markdown to HTML on such popular sites as Stack Overflow, Github, and Reddit. (For example, to eliminate the ambiguity of asterisks, an underline for italics and an asterisk for bold were proposed.) Presumably, CommonMark’s creators consider this a success.
But this isn’t Markdown. Not in name and I wouldn’t say not in spirit.
Around the time CommonMark was being developed, software developer Dave Winer told me something that I still think about: Markdown belongs to whoever uses it. This is literally true because of the license. But it also reminded me of the true importance of free software. We all have an impact on it: using it, adapting it, even forking it.
Whether Gruber intended it or not, Markdown truly belongs to everyone and there are no standards. I’m using a very elderly version of Markdown for Python. Gruber probably still uses his Perl script. Others apply other versions. This is messy. It’s ambiguous. It’s human.
And this is the Way after all.