“Standard” Markdown Controversy

One of the arguments against “Standard Markdown” (now retitled “Common Markdown” after some controversy) would have been obvious from looking at Gruber’s Philosophy section on the Markdown page:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions…

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

(Emphasis per the original text.)

Gruber expressly didn’t care much about the HTML output. If you want to have control over the resulting HTML, then write in HTML — don’t use a deliberately simplified and limited markup language like Markdown. Markdown was not created for the technocrati, it was created for people who don’t wish, for one reason or another, to directly use HTML for writing.

Markdown was not created for coders. People who like to write code loathe inconsistency. They also usually don’t like multiple paths to the same goal. They want to decide on the One True Way to do something, and kill everything else. Witness the Endian wars and other style wars in the programming community over trivialities like indenting. Markdown specifications are properly relegated to back-end implementation. The interpretation and processing of Markdown into HTML is implementation, and implementation is the province of coders.

Other forks of Markdown, such as GitHub Flavored Markdown and MultiMarkdown extend standard Markdown in various ways, and are targeted for their particular use cases. GitHub’s implementation for code blocks, for example, looks like something a group of programmers would want to have; it looks more like code than text. MultiMarkdown added tables and footnotes, among other changes, to create functionality needed in non-web writing contexts.

Why was Gruber okay with Markdown being used in the names of those projects? I don’t know all the details, but my guesses are:

  • They aren’t trying to change Markdown directly. Stuff that’s already in standard Markdown works the way it should. Stuff they added to their flavor of Markdown is there for them to implement and support as they will, without changing the original.
  • They probably asked first, instead of presenting it fait accompli. The presentation of “Standard Markdown”[1] to Gruber was like writing a memo to your commanding officer that includes UNODIR, which is totally a Dick move that will eventually get you fired no matter how effective you are and how right you are in your approach to the situation.
  • It looked like (and probably was) a power-grab. Jeff Atwood has been agitating for standardization and active stewardship of Markdown periodically since at least 2009, and has been openly critical of Gruber’s approach, which is basically to let the coding community sort it out if they want to fork the project.

As far as I can see, Gruber has no problem with forks. He openly praised GitHub Flavored Markdown in 2009. What he understandably has a problem with are changes that are not in the spirit of, and that substantially change the original project.

So why hasn’t Gruber implemented some of the suggested standardization changes? Again, we don’t know directly, but we can infer from his original Philosophy statement that the business of Markdown is to help writers write, and to keep the markup as simple and unobtrusive as possible. Edge cases, inconsistencies, and raw HTML output are all things that the writers and readers of Markdown files should probably never have to consider except to change their favored scripting if the resulting output isn’t to their liking. He has traditionally taken a libertarian stance to the Markdown community, except in cases where someone wants to monkey with his canonical version.

My personal interpretation is that he thinks the competition between implementations will create better results than active direction and stewardship. He basically said as much in this tweet. This has resulted in the creation of GitHub Flavored Markdown and MultiMarkdown, as well as derivative implementations like Fountain, and at this point probably over 100 applications for writing that support either standard Markdown or some flavor of it, so who’s to say that he’s wrong?

I personally moved away from the original implementation of Markdown to MultiMarkdown fairly soon after adopting it for writing, simply because I used footnotes fairly often online, and I needed tables in my offline writing. I’m also not immune to wanting to change some things about it. My two small gripes are that # with or without a space is interpreted as a heading (I would prefer it work only with a space so that hashtags didn’t wreak havoc) and that there was some provision for underlining (Gruber deliberately reserved that solely for indicating a hyperlink), but those are pretty easy to work around.

I currently use @ for tagging because of the # issue, though I’m leaning toward changing back and instead hiding my tags in HTML output through commenting (e.g.: <!-- #blah -->). I can use HTML syntax for underlining (Insert Joke Here: Har-de-har) and I have set up a TextExpander snippet to do so after I type a double underline __ and hit space; no big deal.

What I didn’t do was email John Gruber and say, “Hey, here’s a list of the changes I’m going to make to Markdown. I’d appreciate your input before I release it to the public. kthxbai!”


  1. “We’ve been working on the Standard Markdown project for about two years now. As we got closer to being ready for public feedback, we emailed John Gruber, the original creator of Markdown, two weeks ago (On August 19th, to be precise) with a link to the Standard Markdown spec, asking him for his feedback.”  ↩

    Translation: We’re going public with a standardization process that will effectively remove you from the stewardship of the project you created.

    "We then waited two weeks for a response.

    “There was no response, so we assumed that John Gruber was either OK with the project (and its name), or didn’t care. So we proceeded.”

    It’s not clear from the text of this blog post whether they explicitly gave Gruber a timeline, or just said, “Fuck it, we’re going balls-deep” after their own internal clock indicated they should proceed with the unlubed rogering.