An Introduction to Markdown
A constant challenge for early career researchers and seasoned academics alike is the need to develop more efficient academic writing habits. Experimenting with new software and writing tools is a central part of this process, with plain text writing methods becoming increasingly popular. It is possible, however, for such experimentation to delve beyond the bounds of productivity. The use of advanced plain text typesetting tools such as LaTeX may satisfy our technophilia, but their steep learning curve and often alienatingly dense code leaves them less appropriate as a writing aid in the humanities, at least. It is in this context that the Markdown language stands out as an ideal compromise between versatility and ease of use. In combination with pandoc, a utility that offers the means to convert its text files to a host of other formats, Markdown has the potential to serve as the foundation of precisely the sort of writing system that humanities scholars need.
The advent of plain text writing
The growing number of writers migrating to plain text do so for a range of reasons, the most fundamental of which is its minimalism. Plain text is rightly lauded as a way of stripping out the distractions of formatting and other aesthetic concerns from the writing process, allowing authors to wrestle with their content first. It also results in markedly more compact files than more advanced formats. Smaller file sizes, in turn, render plain text projects more mobile and in many cases more stable, as the majority of text editors are more lightweight, therefore less prone to crashing, than more complex word processors.
Also important is the flexibility of the format. As one of the oldest and simplest file types in existence, plain text is ubiquitous, available on all platforms and editable using any of several hundred free or commercial applications. This contrasts favourably with more exclusive word-processing formats, such as .docx, .rtf, or even their open-source counterpart, .odt, all of which are bound to particular programs. Aside from giving writers the freedom to shop around for the editor best suited to their preferences, this also ensures that plain text remains a free, open-source and universally accessible format, which for many authors is of both practical and ethical importance.
Although it is a useful tool, plain text remains a niche interest, confined to particular disciplines, excluding, for the most part, the humanities. This is partly explained by scholars’ reliance on at least a limited number of formatting features in their writing: headings and sub-headings, clear paragraphing and line spacing and, most crucially, accurate and consistent referencing. All these trappings, as W. Caleb McDaniel notes, demonstrate that academics have ‘done [their] homework’ and met the minimum standards of professional competence in their discipline.
For those with less time, patience or technical proficiency to experiment, these needs can most easily be met with more fully featured word processors. With a moderate investment of time and effort, however, Markdown can provide the same functionality alongside all the advantages of plain text writing.
Introducing Markdown and pandoc
Markdown, rather confusingly, is one of a variety of markup languages—languages designed to make writing quicker and easier by separating the content of a particular document from information about its form. Perhaps the best-known markup language, still as prevalent as ever despite being as old as the public internet, is HTML, though numerous others, of varying levels of specialization, also exist.
Markdown was developed by John Gruber and Aaron Swartz in 2004, with the aim of creating a markup language easier to read and write in than HTML, but whose output could subsequently be converted to ‘structurally valid’ HTML. Though originally intended to streamline the creation and publication of web content, the language is equally suitable for lengthier writing work. Its prioritization of readability and simplicity, in particular, gives it several advantages over other markup or typesetting standards such as HTML or LaTeX, another favourite of many academics making the switch to plain text. In comparison with these languages, Markdown employs less obtrusive, more intuitive formatting; it can be learnt far more quickly; and it is more straightforward to convert its text files to other formats.
There is no standardization in the Markdown universe, and various competing versions exist. The flavour of Markdown being advocated here, however, is the one packaged with pandoc, a cross-platform file conversion utility created by philosophy professor John MacFarlane in 2006. Pandoc functions as a veritable ‘swiss-army knife’ of document conversion, enabling users to convert files in any of fourteen different formats (including Markdown) to numerous other formats (such as .docx, .odt and .pdf). It is therefore an invaluable tool in its own right, though it is the comprehensiveness of its version of Markdown that recommends it as the basis for an entire alternative writing workflow.
An in-depth tutorial on pandoc and its augmented variety of Markdown would expand this post beyond reasonable limits. As a starting point, however, interested writers are advised to have a look at the attached guide, which provides an overview of writing, referencing and converting academic texts using pandoc.
The guide is offered as both a Markdown source file (.txt) and a converted Word document (.docx), allowing the plain text formatting tags to be compared directly to their output. It is hoped that this will at least hint at the power and simplicity of Markdown, and encourage more humanities researchers to adopt it in their work.
- John MacFarlane’s pandoc website: the main site for downloading and installing pandoc (and its version of Markdown)
- Sublime Text’s website, for an example of a powerful and visually appealing cross-platform text editor that works particularly well with Markdown
- Christopher Grainger’s excellent introductory article on using Markdown and pandoc for academic work
- ‘The Programming Historian’s equally informative introduction from (unsurprisingly) a historian’s perspective
- (optional) Kieran Healy’s slightly more involved article on the same theme
- (optional) Plaintext Productivity’s instructions on setting up Sublime Text to automate Markdown conversions with pandoc
And for the opposing view…
- ‘The Lab and Field’s article, with the cautionary message that this sort of workflow will not suit everyone
Powered by Facebook Comments