The Markdown Movement: Writing's Influence on Markup

Contributor: Aaron Beveridge
Affiliation: The University of North Carolina at Greensboro
Email: akbeveri at uncg.edu
Released: 20 December 2017
Published: Spring 2018 (Issue 22.2)

Introduction

This webtext introduces Markdown—a new markup language for web writing and multimodal webtext production. Markdown can do many things, but primarily, it provides a writer-friendly alternative to other markup languages such as HTML/CSS. By limiting its “code” to a handful of styling and markup conventions, Markdown simplifies and streamlines the “Turing complete” complexity that accompanies other markup systems. A Turing complete programming language can conduct the same computations as any other general purpose programming language. The more popular general purpose programming languages, such as C or Python, are examples of turing complete languages, and web design systems such as JavaScript and HTML5/CSS3 have expanded to provide similar computational power as the general purpose programming languages. The downside of this improved computational power for web design systems is that it has lead to a substantial increase in the learning curve for systems such as JavaScript and HTML/CSS. Markdown responds to this increased complexity by providing web writers and digital rhetoricians an accessible yet powerful markup alternative.  

For writers who are used to producing documents in WYSIWYG (What You See Is What You Get—pronounced: “wiz-ee-wig”) systems—such as Microsoft Word or Google Docs—the transition to contemporary web design tools can be cumbersome and intimidating. While WYSIWYG writing tools provide an accessible writing environment, they are often incompatible with many types of automated web production/design systems (such as automated blog generators or content management systems). Contemporary webtext production often requires the delivery of digital artifacts and multimodal documents to multiple networks, simultaneously. For example, a writer might first produce a webtext for their blog, and then share it on multiple digital networks as well. This can be as simple as resharing a URL to the original blog post on Twitter or Facebook, or as complex as re-delivering documents in multiple digital formats through automated conversion processes—what we might otherwise rhetorically understand as multi-delivery. Technical and professional scholars research issues surrounding multi-delivery by studying content management approaches in technical and professional settings, but more generally, the challenges related to multi-delivery are now common to many forms of digital, multimodal, and webtext production.   

While many automated web writing systems require writers to learn JavaScript and HTML/CSS, many of the more accessible "cloud" systems force writers to work within a single/closed web design ecosystem, such as Wordpress or Wix. Markdown is a timely addition to the web writing landscape because it bridges the gap between the two extremes. On one hand, Markdown provides writers a visually clean and “writerly” environment (similar to WYSIWYG systems). Yet, on the other hand, Markdown also provides writers the ability to automate their multimodal production and insert code and programmable functions into their webtexts. The following video provides an introduction to Markdown and shows how it bridges the gap between these two extremes:

This webtext provides a comprehensive introduction to Markdown, explaining the relevance of the Markdown movement for rhetoric and writing studies, as well as providing a brief history of Markdown that explains how its development was influenced by the pragmatic needs of writers. In addition to the introductory video above, I have created three other videos that serve as the primary content for this webtext: "Getting Started with Markdown," "Your First Markdown Webtext," and "Advanced Markdown." This webtext's content can be viewed/read linearly, or it can be used as a reference tool for teaching/learning markdown--allowing readers to simply watch and follow the video demonstrations/tutorials. Readers of this article are encouraged to view the "Getting Started with Markdown" video because it provides a quick overview of markdown resources, as well as providing a brief demonstration of webtext production with Markdown. The last two videos ("Your First Markdown Webtext" and "Advanced Markdown") are meant for readers who specifically want to learn to use Markdown to produce webtexts and other multimodal documents. And finally, the remaining two sections of text ("Markdown's Relevance for Rhetoric and Writing Studies," and "A Brief History of Markdown") provide additional information for scholars interested in Markdown's relevance for writing studies and its history and continued development. As with the videos, these two sections of text can be read linearly along with the rest of the content in the article, or they can be used as resources in a non-linear fashion, depending on the needs of the reader.

Markdown's Relevance for Rhetoric and Writing Studies

Generally speaking, questions about learning to program in rhetoric and writing studies fall within discussions about computer literacy as they relate to digital literacy. For web design and the writing of HTML/CSS, these questions have been around since the emergence of the Internet. From Paul J. LeBlanc's 1993 Writing Teachers Writing Software to the 2016 CCCC chair's address given by Joyce Locke Carter—the calls for scholars, researchers, and teachers to consider programming as a form of writing have continually re-emerged since Richard Lanham coined the term digital rhetoric in the late 1980s. These discussions have been re-contextualized by critical code studies and through interdisciplinary scholarship in the digital humanities, as evidenced by the Enculturation special issue, "The Role of Computational Literacy in Computers and Writing," and by the Literacy in Composition Studies special issue, "Understanding Computer Programming as Literacy."

The question of "do I need to learn to program?" continues to spark quite a bit of controversy, connecting tangentially to composition studies' debates about "skills" and "process," and more recently to debates about programming’s potential function as a "gatekeeper" in the digital humanities (DH). Instead of setting up programming (among other "maker" skills) as gatekeeping-skillsets for DH researchers and scholars, the broad response has been a move to define the digital humanities as the "big tent," allowing for an expansive and inclusive view of "what counts" as DH scholarship (see: Debates in the Digital Humanities, 2012 and 2016 editions). For scholars and researchers in rhetoric and writing studies, the question of “do I need to learn to program?” is often less about disciplinary gatekeeping (although accessibility remains a valid concern) and more about the pragmatics of writing and multimodal production (see: the Enculturation special issue on coding literacy). As many academic journals continue to move to open standards and web publishing models, learning basic web design opens many more avenues for producing and sharing new scholarship in digital rhetoric and writing studies. However, as the “Introduction: What is Markdown?” video shows, writing an article in a markup language like HTML is less than ideal for scholars who are new to web design.

However, for writers who want more digital design possibilities than those that are 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, described the importance of markup for writers: 

Certainly, there many writers who are comfortable designing webtexts in HTML, but many writers continue to prefer WYSIGYG environments similar to standard word processing applications like Google Docs or Microsoft Office. However, WYSIGYG systems remain limited, and what writers gain in ease-of-use and user-friendly interaction, they often give up in in-line control and programmable functionality. As Nicholas Mauriello et al. (1999) in “Reading between the Code” and Kristin L. Arola (2010) in “The Design of Web 2.0” argue in their articles, giving over to WYSIWYG writing environments altogether means relinquishing too much control over design and layout. At the same time, expecting writers to always code in full JavaScript and HTML/CSS is also unrealistic.

In her 2016 keynote address to the Conference on College Composition and Communication, Joyce Locke Carter argued that the phrases “my startup company” or “my new app” should become “desirable and normal–as normal as anyone who mentions ‘my new book,’ or ‘my research,’ or ‘my advocacy.’” Carter explained that we no longer need to see such applications of writing as fringe or marginal, and that “taking this step doesn’t require any additional skills–what is called for is a different mindset, not skillset.” For Carter, this “mindset” was less about “training or specialization” and more about acknowledging the maker identities that are already at work in the field: “designers, architects, engineers, User Experience specialists, technologists–and if you read the convention program carefully, you’ll see all of these identities are already at the C’s this very week” (390). 

This is why Markdown is more of a movement than a technological innovation, and it falls in line with the “mindset” that Carter encouraged in her keynote address. From a technical standpoint, everything that Markdown can do 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 a specific design aspect that writer’s wish to add to their webtext. This is the Markdown movement—focusing on the pragmatic experience of the writer first and foremost, and requiring that technical functionality follows from the writer's pragmatic concerns.

A Brief History of Markdown

Markdown was created and released in 2004 by John Gruber. While open source software development often strives for transparent and effective collaboration, this does not mean that it occurs without friction or disputes among developers. While Gruber was the initial creator of Markdown, many new versions and variations emerged during Markdown’s early years of development. Many programming languages eventually developed their own versions of Markdown: there are versions of Markdown available for Reddit, GitHub, and StackExchange. In addition to these variations, countless other sites and tools have developed some variation of it for webtext and multimodal writing. Even WordPress has Markdown support for creating blogs and editing web pages. The fracturing and expansion of Markdown happened so quickly that many developers quickly began to call for work to standardize Markdown's syntax. Unlike for HTML, there is no Internet standard for Markdown. The brief history below explains Markdown’s first decade of development, its move toward standardization, and its establishment as an accessible alternative to HTML. Drawing heavily on blog articles about Markdown written by Jeff Atwood, co-founder of stackoverflow.com, this brief history explains the motivation and rationale behind the effort to standardize Markdown’s markup syntax.

In 2009, Atwood wrote on his personal blog a scathing critique of Gruber’s oversight of Markdown, titling the post: “Responsible Open Source Code Parenting.” Atwood retorted: 

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/hacking related blog codinghorror.com since 2004), but also because many of his 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 programming related questions. It 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. Furthermore, Atwood’s newest open source development project, Discourse, attempts the lofty goal of improving Internet discourse through technological innovation. Atwood’s investment in Markdown, therefore, is not only technical, as a developer, but also pragmatic, as a writer and discursive community developer.

In 2008, Atwood wrote 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 it also explains the crucial impetus for the Markdown movement. Since Stack Overflow is 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 argued that if “you can sling code, a little bit of presentation markup is child’s play.” However, Atwood also countered 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 assumed 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 remained the pragmaic experience of the writer and the accessibility of the site. To make this point, Atwood discussed Wikipedia’s markup language as a point of departure: 

What became clear in Atwood’s 2008 post is that Stack Overflow wanted 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. The question, then, 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 wrote a post titled “The Future of Markdown” in which he implored Gruber to support a standardization effort for Markdown’s open source development, writing: “So I’m asking you, John Gruber: as the original creator of Markdown, will you bless this endeavor?” Atwood went on to explain his motivations for such a request: 

If Markdown is more “movement” than innovation, as this webtext argues, 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, and Gruber’s original Markdown was intended to work in conjunction within a programming language called Ruby. Ruby was responsible for converting Markdown into HTML for publishing to the web. By creating Pandoc, Markdown could function more universally, opening the possibility of converting 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 (conversion) utilities. John MacFarlane, chair of the Department of Philosophy at UC Berkeley, started to develop Pandoc in 2006 as an open source tool for broad-scale document conversion. As the "Advanced Markdown" video in this article shows, Pandoc allows for more complex uses of Markdown, such as automating the creation of ebooks from multiple Markdown files. Using Pandoc, Markdown files can also be used to compile more complex websites and blogs. Therefore, MacFarlane and the Pandoc conversion tool he created have greatly opened the possibilities for how Markdown can influence the web writing landscape.

Working with MacFarlane, Atwood announced on September 3, 2014 that he had assembled a group of representatives from Reddit, GitHub, Stack Exchange (owners of Stack Overflow), and Meteor (an open source mobile development platform) to release standard Markdown specification for ongoing and future development. What was most exciting about this announcement is that most of the spec for Markdown had been written by 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 5, Atwood posted a follow-up announcement, in the blog post "Standard Markdown is now Common Markdown," that their team will be changing the URL from http://www.standardmarkdown.com to http://www.commonmark.org, following an email he received from Gruber. Atwood explained in the follow-up post that he had emailed Gruber asking him to be part of the standardization team back in 2012, and that Gruber had never responded to the email. And then, again in August 2014, Atwood had 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 went 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 now, 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 used that single line to link back to his follow-up blog post explaining Gruber’s continued disinterest and lack of involvement with Markdown.

In April 2015, the Internet Engineering Steering Group recieved a draft letter to begin the standardization process for making Markdown an official Internet media type for the Internet Engineering Task Force. Developers were invited to submit use cases for variations of Markdown, and this process remained open until April 2016. It is unclear if formal standardization will be completed for Markdown, but for now, it appears as if the friction regarding Markdown’s future is settled. Gruber continues to receive the credit for being Markdown’s creator, but open development and collaboration beyond his initial investment have led to Markdown becoming a viable markup alternative for Internet writing and web design.

Additional Markdown Tutorials and Resources

The following resources are for web writers interested in additional possibilities for Markdown as a general web writing tool. The first video, "Your First Markdown Webtext," is a tutorial video for writers who want help in creating and publishing their first Markdown webtext to the web, and the second video, "Advanced Markdown," demonstrates the advanced design/automation possibilities that are provided by Pandoc. Lastly, the table below provides links to additional resources that utilize Markdown for other forms of multimodal production.  

References

Arola, Kristin L. (2010). The design of web 2.0: the rise of the template, the fall of design. Computers and Composition, 27(1), 4–14. https://doi.org/10.1016/j.compcom.2009.11.004

Atwood, Jeff. (2008, May 13). Is HTML a humane markup language? Coding Horror. https://blog.codinghorror.com/is-html-a-humane-markup-language/

Atwood, Jeff. (2009, December 29). Responsible open source code parenting. Coding Horror. https://blog.codinghorror.com/responsible-open-source-code-parenting/

Atwood, Jeff. (2012, October 25). The future of markdown. Coding Horror. https://blog.codinghorror.com/the-future-of-markdown/

Atwood, Jeff. (2014, September 4). Standard markdown is now common markdown. Coding Horror. https://blog.codinghorror.com/standard-markdown-is-now-common-markdown/

Carter, Joyce Locke. (2016). 2016 Chair’s address: Making, disrupting, innovating. College Composition and Communication, 86(2), 378–408.

Dilger, Bradley, & Jeff Rice (Eds.). (2010). From A to A: Keywords of markup. Minneapolis: University of Minnesota Press.

Gold, Matthew K. (2012). Debates in the digital humanities (2012 Edition). Minneapolis: University of Minnesota Press. http://dhdebates.gc.cuny.edu/debates/1

Gruber, John. (2004, December 17). Markdown. Daring Fireball. https://daringfireball.net/projects/markdown/

LeBlanc, Paul J. (1993). Writing teachers writing software: creating our place in the electronic age. National Council of Teachers of English.

Mauriello, Nicholas, Gian S. Pagnucci, & Tammy Winner. (1999). Reading between the code: the teaching of HTML and the displacement of writing instruction. Computers and Composition, 16(3), 409–419. https://doi.org/10.1016/S8755-4615(99)00020-1

Sample, Mark & Annette Vee. (2012). Introduction to the role of computational literacy in computers and writing. Enculturation. http://enculturation.net/computational-literacy

Vee, A. (2013). Understanding Computer Programming as a Literacy. Literacy in Composition Studies, 1(2), 42–64. https://doi.org/10.21623/1.1.2.4