Digital Humanities
@ Pratt

Inquiries into culture, meaning, and human value meet emerging technologies and cutting-edge skills at Pratt Institute's School of Information

Markdown/Pandoc Skillshare

Important links:

Pandoc (Github)
LaTeX installer (for converting plain text to PDF)

This video tutorial provides a brief introduction to Markdown and Pandoc.  Used in concert, these tools can help authors produce a variety logically formatted containers for content from plain text files.  The tutorial will focus on the basics and benefits of Markdown syntax and execute a few useful file format conversions using Pandoc command prompts.
Back in 2004, John Gruber released Markdown  on his website as a text-to-HTML conversion tool.  The goal was and is to allow for the implementation of a set of simple, human-readable notations within a body of text that indicate the structure of the text (e.g. which part is a paragraph, which part is a block-quote, etc.).  These notations can then be parsed by a software conversion tool to create HTML containers that save the author the tedium of writing out HTML in order to cohere their document to a web environment.

Increasingly, researchers across academic disciplines have advocated for the use of plain text formatting as a means of taking control of both document preservation and transmission.  The primary benefit of using plain text is that it separates text from typesetting, which have become entwined in personal computing with mixed results.  Commercial word processors like Microsoft Word offer intricate typesetting features to manage the visual impact of bodies of text.  These enable a plethora of presentation options, but the effects that these settings have on characters committed to a blank document are not always clear.  Even the simplest Word template for composition involves some program-centric encoding that make the behavior of the text unpredictable if transferred to a different format.  Basically, what you see is not what you get.

What’s more, while proprietary-ish formats like .docx or .pdf  have become more open in the last few years, they require expensive software to access full feature sets and translate and convert documents.  In the event that they cease to be promoted by their originating companies, these formats may become more difficult to open and edit as the market for business-centered document solutions rolls along.  Plain text by its very nature is open standard and future-proof.

The basic principle at work with Markdown, making semantic relationships within the text both explicit and human-readable, makes it versatile.  Markdown’s extensibility makes it an important tool to digital humanities researchers, who often publish work across multiple formats both in print and online.  Its basic syntax distills the essential elements in a body of writing, those that will be significant to the author’s meaning in both a journal article and a blog post.  Being able to conceptualize one’s writing as independent from the many visual forms it can take is a huge advantage in a discipline that fosters collaboration and remixing of ideas.

Markdown becomes more versatile in the constellation of conversion tools encompassed by Pandoc.  Pandoc’s default approach to parsing the Markdown convention at use in a document is geared for academic formatting.  This means that footnotes and citations, the primary methods by which knowledge is built and networked within scholarly publications, can be liberated from the elaborate apparatus through which word processors format them.  Incorporating Markdown and Pandoc in a project workflow does not require extensive coding know-how, which makes doing so less likely to be disruptive for general users.  The tutorial should be approached as a starting point for using Markdown in conjunction with other forms of text creation, and as a bridge to the more advanced tasks that can be tackled with Markdown and Pandoc.

Further reading:

Annie Lin and Ken Sherwood, “Markdown Not Markup – Easy Everyday Workflow for the Web”
Dennis Tenen and Grant Wythoff, “Sustainable Authorship in Plain Text using Pandoc and Markdown”
W. Caleb McDaniel, “Why (and How) I Wrote My Academic Book in Plain Text”
Chris Forster, “About 1400 Words of Skepticism about Markdown and an Imagined Alternative”

Leave a Reply

Your email address will not be published. Required fields are marked *