"The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that 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."

John Gruber

Markdown’s Relevance for Writing Studies

For writers who want more digital design possibilities than what is commonly offered by limited GUI (graphical user interface) text editors on webpages, coming to terms with some variation of markup is unavoidable. Bradley Dilger and Jeff Rice, editors of From A to <A>: Keywords of Markup, describe the importance of markup for writers:

Markup, also called tagging, can be attributed to text, images, metadata, design, and behavior, affecting how readers engage with and encounter information. Markup bolds and centers, generates links, positions images on pages, produces output, and so on. Markup organizes and displays information; it institutionalizes practices relevant to online communication. Markup is the first thing Web writers engage, whether or not they imagine writing as tagging, coding, or marking up. Markup is communication. Markup is writing. (xi)

As the introduction video to this webtext argues, HTML is not very writer-friendly. Certainly, there are plenty of writers who are already comfortable designing webpages in HTML, but many writers continue to prefer WYSIGYG environments similar to standard word processing applications like Google Docs or Open Office. However, WYSIGYG environments for Internet writing and web design are fairly limited, and what writers gain in ease-of-use and user-friendly interaction they often give up in terms of in-line control and tagging functionality. While the in-line control and tagging functionality of HTML is no doubt powerful, viewing “page source” on any webpage quickly reveals a tagging system that is both difficult to read and just as difficult to write within. As Nicholas Mauriello et al. in “Reading between the Code” and Kristin L. Arola in “The Design of Web 2.0” similarly argue in their articles—giving over to WYSIWYG writing environments altogether means relinquishing too much control over design and layout, but, at the same time, expecting writers to always code in full HTML is also unrealistic. Markdown attempts a compromise between these two approaches, and bridges the divide between WYSIGYG writing and full HTML tagging.

This is why Markdown is more of a movement than a technological innovation. From a technical standpoint, everything that Markdown is capable of as a markup language is far more extensive and efficient in other variations of markup---such as HTML and LaTeX. Rather, what makes Markdown “innovative” is its resistance to too-much technical capability in favor of the pragmatics of writing. By limiting Markdown’s markup syntax to a handful of conventions and the most commonly used in-line formatting instructions, writers are provided with a writing environment that is far less cluttered with tags and code. Yet, Markdown does not give up on tags and code altogether. In fact, most Markdown parsers will allow users to drop in full HTML code whenever Markdown’s syntax is too limited for some design aspect they wish to accomplish. This is the Markdown movement—focusing on the pragmatic experience of the writer first and foremost, and requiring that technical functionality follows pragmatic concerns.

A Brief History of Markdown return to top

Markdown was created and released in 2004 by Mark Gruber. While open source software development often strives for transparent collaboration, it does not mean that open source collaboration occurs without friction or disputes among developers. While Gruber was the initial creator of Markdown, many new versions and variations emerged during Markdown’s first years of development. Most programming languages developed Markdown parsers or libraries---there is GitHub flavored markdown, Reddit, GitHub, StackExchange, and countless other sites that have developed some variation of Markdown for writing and designing posts on their sites. Even WordPress has markdown support for creating blogs and editing web pages. This fracturing and expansion happened so quickly that many developers quickly began to call for work to standardize Markdown's syntax. Unlike HTML, there is no Internet standard for Markdown syntax. The brief history below explains markdown’s first decade of development. Drawing heavily on the blog accounts provided by Jeff Atwood, co-founder of stackoverflow.com, this short narrative will explain some of the motivations and rationale behind the effort to standardize Markdown’s markup syntax.

In 2009 Jeff Atwood, co-founder of Stack Overflow, wrote on his personal blog a scathing critique of John Gruber’s oversight of Markdown and he titled the post: “Responsible Open Source Code Parenting.” Atwood, showing his frustration with Gruber, explains:

It’s almost at the point where John Gruber, the very person who brought us Markdown, is the biggest obstacle preventing Markdown from moving forward and maturing. It saddens me greatly to see such negligent open source code parenting. Why work against the community when you can work with it? It doesn’t have to be this way. And it shouldn’t be.

Atwood’s role in the history of Markdown is relevant to writing studies, not only because Atwood is an avid writer and blogger (maintaining his programming blog codinghorror.com since 2004), but many of Atwood’s software projects have been discursive writing technologies. Stack Overflow is the largest programming and technical discussion site on the Internet—providing a forum for users to quickly ask and answer questions. Stack Overflow has been such a useful tool for learning how to program that simply copying and pasting programming errors/questions into Google’s search engine will often return a Stack Overflow question/answer as the top search item. And Atwood’s newest open source developmnet project, Discourse, attempts the lofty goal of improving Internet discourse through technological innovation. Atwood’s investment in markdown, therefore, is not only a technical investment as a developer, but also a pragmatic investment as a writer and discourse community developer.

In 2008, Atwood delivered a post on his blog titled: “Is HTML a Humane Markup Language?” The post explains Stack Overflow’s decision to use Markdown for posting questions on the site, and, as a result, the post also explains the crucial impetus for the Markdown movement. As a site for obtaining answers to questions about programming and other technical issues, Atwood explains why they decided not to provide a simple WYSIWYG editor for users to post questions to the site: “I have one iron-clad design guide: this is a site for programmers, so they should be comfortable with basic markup.” Atwood argues that if “you can sling code, a little bit of presentation markup is child’s play.” However, Atwood counters those assumptions when he explains why Stack Overflow chose Markdown over other lightweight markup languages. Given that Stack Overflow’s audience is often programmers, he is able to assume a much higher technical knowledge and a minimum set of coding skills than other sites or organizations. Yet, even with such an assumption, Atwood’s primary concern remains the pragmaic experience of the writer. To make this point, Atwood discusses Wikipedia’s markup language as a point of departure:

It’s an effective markup language, but I think you’ll agree that it’s more intimidating than humane. […] I’d argue that writing a Wikipedia entry is a step beyond mere presentational markup; it’s almost like coding, as you weave the article into the Wikipedia gestalt. (Incidentally, if you haven’t ever edited a Wikipedia article, you should. I consider it a rite of passage, a sort of internet merit badge for anyone who is serious about their online presence.)

What becomes clear in Atwood’s 2008 post is that stackoverflow wants to provide users with some measure of control over design through an in-text lightweight markup language, but the pragmatics of writing in a fully-coded environment remove the ease-of-production users expect from WYSIGYG writing environments. Markdown attempts to bridge this gap by providing a limited set of syntax conventions without becoming a full-blown version of HTML on its own. The question is where do developers of Markdown draw the line? How many tagging or markup conventions are too many for Markdown? How much additional functionality should be added?

The problems posed by these questions led to the friction between Atwood and Gruber. In 2012 Atwood writes a post titled “The Future of Markdown” in which he implores Gruber to support a standardization effort for Markdown’s open source development: “So I’m asking you, John Gruber: as the original creator of Markdown, will you bless this endeavor?” Atwood explains his motivations for such a request:

I freaking love Markdown. I love it so much that I want to see it succeed and flourish over the next 20 years. I believe the best way to achive that goal is for the most popular sites using Markdown to band together and take ownership of Markdown as a standard. I propose that Stack Exchange, GitHub, Meteor, Reddit, and any other company with lots of traffic and a strategic investment in Markdown, all work together to come up with an official Markdown specification, and standard test suites to validate Markdown implementations. We’ve all been working at cross purposes for too long, accidentally fragmenting Markdown while popularizing it.

If Markdown is more “movement” than innovation, as this history suggests, then Atwood is a key motivator in the direction it has taken. The closing lines of his 2012 post are a call to action: “I’d really prefer not to fork the language; I’d much rather collectively help carry the banner of Markdown forward into the future, with the blessing of John Gruber and in collaboration with other popular sites that use Markdown. So…who’s with me?”

Before continuing the story of Markdown’s development, it is important to weave into this narrative the development of an adjacent tool called Pandoc. Markdown always requires a conversion utility. Gruber’s original Markdown was intended to work in conjunction within a Ruby parser that converted Markdown syntax to HTML. However, Pandoc converts Markdown into many other file formats, including: DOCX, PDF, HTML, RTF, ODT, EPUB. While using Markdown within a single web application like Stack Overflow provides a meaningful case for examining its initial development, Markdown’s true potential is realized through the functionality provided by Pandoc and other similar parsing utilities. John MacFarlane, chair of the Department of Philosophy at UC Berkley, started to develop Pandoc in 2006 as an open source tool for broad scale document conversion. Pandoc’s conversion utility provides Markdown users with a far greater range of possibilities. Collections of Markdown files (with each file being a chapter, for example) can be converted into ebooks. Markdown files can also be used to compile more complex websites and blogs. While Pandoc makes all of this possible by broadly converting Markdown, it is important to note that Pandoc also has its own variation of Markdown—providing yet another example for why Markdown standardization efforts became so crucial. With yet another variation in Markdown syntax provided by Pandoc’s own version of Markdown, this reiterates the necessity of Atwood’s call-to-action.

On the September 3rd of 2014 Atwood announced on his blog that he is working with a group of representatives from Reddit, GitHub, Stack Exchange (owners of Stack Overflow), Meteor (open source mobile development platform) and Pandoc to release standard Markdown specification for ongoing and future development. What is most exciting about this announcement is that most of the spec for Markdown is written by professor John MacFarlane. However, the effort was met with one last bit of controversy between Atwood and Gruber. Initially, the group placed their spec at http://www.standardmarkdown.com. However, three days later on September 5th, Atwood posted a follow-up announcement changing from www.standardmarkdown.com to http://www.commonmark.org following an email from John Gruber. Atwood explains in the follow-up post that he emailed Gruber asking him to be part of the standardization team back in 2012, and Gruber never responded to the email. And then, again in August of 2014 Atwood asked Gruber if he would provide feedback on the standardized Markdown spec before they released it, and still Gruber did not respond, according to Atwood. In the follow-up post, Atwood goes out of his way to apologize to Gruber and once again give him credit for creating Markdown, but if you go to http://www.standardmarkdown.com a single line remains showing Atwood’s frustration with Gruber: “This domain was disabled at the request of John Gruber.” Atwood could have disabled the domain altogether, but instead that single line links back to his follow-up blog post explaining Gruber’s continued disinterest and lack of involvement. Two years later, Atwood continues to keep that original domain up and running.

In April of 2015 the IESG recieved a draft letter to begin the standardization process for making Markdown an official Internet media type for the Internet Engineering Task Force. Developers have been invited to submit use cases for variations of Markdown, and this process remains open until April of 2016. For now, it appears as if the friction regarding Markdown’s future is settled. John Gruber continues to get credit as Markdown’s creator, but open development and collaboration has led to Markdown becoming a viable markup alternative for Internet writing and web design.

return to top