Markdown and Standards

“github flavored markdown” sounds like a fork. “standard markdown” sounds like ownership. Not my project but shitty

 — tweet by Justin Williams

This tweet caught my eye after reading Coding Horror’s most recent post about “Standard” Markdown. Digging into the project and the origins of the Markdown project I’ve developed some thoughts.

Markdown History

Markdown is a plain text formatting syntax created by John Gruber initially released in 2004. The syntax was inspired by plain text email and readability while allowing simple conversion to HTML for web publishing. Since the initial release in 2004 it has been used in a wide variety of ways, from email writing, Q/A platforms, online discussions, source control, and many more. Driving this mechanic is the lightweight and easily readable formatting. An average person can understand a Markdown formatted document without seeing the conversion. It’s plain text readability and subsequent HTML conversion allows both easy editing and display on the web. These are distinct advantages over WYSIWYG editors and other markup languages.

Flavors like ice cream

Markdown is the lingua franca of online writers and README files everywhere. It’s popularity is second only to actual plain text where people lay out things with tabs and spaces, eschewing any sort of secondary HTML conversion. As one of the best known formatting syntaxes online today, there are generic packages for every popular language, be it Python, Ruby, Java, or JavaScript. These implementations all differ slightly in their handling of syntax, particularly the edge cases inevitable in any syntax.

Aside from the generic packages there are multiple “flavors” of Markdown implemented for specific needs. GitHub deals often with code chunks, so they support fenced code blocks with optional syntax highlighting, tables, and strikeouts. Reddit supports superscript and strikeouts. StackOverflow supports URL-autolinking, different syntax highlighting hints, tagging, and an even more limited subset for commenting.

These custom-fit solutions are better than one-size-fits-all because it enables people to take the spirit of the syntax (plain text formatting) and expand on it based on their specific needs without worrying about breaking a specification or standard. Standards are useful when everyone needs to be speaking exactly the same stuff because you can’t depend on the consumer accounting for your quirks. Successful standards aren’t really successful at all. They are restrictive, limiting innovation and removing extensibility by forcing everyone to play together.

Standardization

There is a very big difference between encouraging and supporting multiple flavors and custom extensions to a format and attempting to standardize it. Standardization after the fact is a power grab designed to steal attention and force a dominant implementation. Pushing a specification has ulterior benefits for the writers of said specification, specifically around interoperability and platform support.

Supporting Markdown “source” cross-platform is a difficult job, one I think it is ill-suited for. The specific needs of any given implementation makes it difficult to foresee how that could be supported in another implementation. For example, does Reddit need fenced code blocks? Does StackOverflow need support for admonitions? I doubt both.

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.

—from Markdown Syntax

The syntax is intentionally limited to a very small feature set. It wasn’t designed to handle tables of content, inter-site links, tables, or HTML class fiddling required by formats that provide inter-platform support. There is much better formats for those use cases. reStructuredText is primarily a documentation tool widely used in the Python community. Wiki markup supports a powerful syntax capable of supporting a wide variety of use cases. LaTeX is all but forgotten in online communities. These formats offer better support for platform interoperability at the cost of higher barrier to entry in terms of syntax.

Conclusion

To re-state Justin’s comment above, calling this project “Standard” Markdown is a hijack of the Markdown name. This is a new flavor that redefines some edge cases and offers little if any additional functionality to the language such as extensions or extras. Markdown deliberately avoids being a standard to promote the growth of lightweight plain-text formatting.