In the last few years a new-ish markup language1 called markdown has rapidly become a semi-standard2 for geeks and programmers across the internet as a way of easily writing text documents that are both human- and machine-readable. I’m going to argue that for many academics, even in the more techno-phobic humanities, should think about writing using these tools. Here I’ll describe one way of using a workflow with Markdown to easily go from plain-text files to presentable academic PDFs or Word documents.
Why should I use Markdown?
There’s plenty of good reasons to use Markdown to do your work, but here are my top three for academics in the Arts and Humanities:
You can do your work anywhere. Markdown is plain-text. That means that any device with access to the file can edit it as well as any other. Any device. That includes Mac, Linux and Windows PCs of any vintage, phones, tablets, chromebooks, your granddad’s computer that hasn’t been updated since 1997. Anywhere.
You can convert it to any format. The Pandoc converter that we’re going to use can handle just about anything you can throw at it. This includes PDF, Word docs, LaTeX, Open Office docs, even web pages. It also has extremely robust support for referencing in any style imaginable. You type
[@Author2011]and the converter does all the hard work.
It makes it easy, in fact practically forces you to write more. No more messing around trying to get the references just so. No more footnotes swallowed by the latest version of word. No more font sizes, headings, endnotes, tables, lists. All formatting is specified using simple ‘tags’ and handled in the conversion by Pandoc. Shut up and write!
Oh, the Humanitites!
I know that in the humanities we tend to be fairly averse to changing up the way we work, particularly with technology. Having a routine is important when there’s no specification or methodology to follow, no lab tests that need doing. But I promise you that one afternoon spent learning Markdown (and it probably won’t even take that) will mean hours saved down the line when it comes to changing the reference style (again!) for that journal article, or being able to do work wherever you’re stuck because who cares what version of Word is installed if all your files are in plain text?
Some of this is a little farther along towards the computer-nerd end of the geek-spectrum than most of us are comfortable with, but it’s plenty achievable if you dust off that logical, scientific corner of your brain that so rarely seems to get used. It might even enjoy the exercise!
What do I need?
To use the setup I’m going to describe you need several pieces of software, and then there are a few others which will make it significantly easier. I use a Mac, and haven’t used a Windows PC for a long time, but I’m going to try to make this fairly agnostic as far as your operating system is concerned. If any Windows users want to correct or suggest anything, please do use the comments form at the bottom of the page.
- Pandoc which will convert the markdown to just about any format you can think of. Windows, Mac and Linux versions available from the Downloads Page along with brief instructions on how to install.
- Some sort of TeX distribution if you want to use PDF output. For Mac users that’s MacTeX - the much smaller Basic TeX will work just fine. For Windows I believe that MiKTeX is the way to go. These are the big, complicated bits of software that do all the heavy lifting when it comes to converting your documents – and which you’ll never have to touch.
- That’s it!
You’re probably also going to want a few other bits and bobs. To start with, keeping all your files in sync with Dropbox or Google Drive is the obvious way to make sure you can always access your files. You can edit your files in any text editor, like Notepad on Windows or TextEdit on OS X, but having a good editor which can highlight the syntax makes it much easier. On a Mac the obvious choice is Text Wrangler, on Windows I believe that Notepad++ is currently the front-runner.3 There are some other small utilities that make using markdown easier on both platforms, such as previewers (I use Marked which is fantastic), menu add-ons which let you quickly convert to markdown and more.
I use Zotero as a reference manager, which is free, stable and fully-featured. The details on how I have it set up are below. You could use any reference manager you liked, though, as long as it could export to BiBTeX or BibLaTeX – they nearly all can. Zotero is Free Open-Source Software, as is Pandoc. I think that this is pretty important, particularly in academia, but that’s a story for another post.
How do I start?
Other people have covered this much better than me,4 but once you’ve installed Pandoc, all you really need to do is start writing – after a while you’ll start to work out the tools and tricks that will work best for you. I’ve detailed my workflow below to give you an idea of one way this might work:
This is a very robust setup for using Scrivener for writing and Zotero as a reference manager. Whatever you end up using, the Zotero part alone is well worth noting for bomb-proof citations and referencing.
Parts of this process will require you to use the Terminal app on OSX. You can find it in the folder
/Applications/Utilities or by using Spotlight with
⌘-SPACE. Any of the text that is formatted in code blocks:
should be typed exactly as is, or can be copied-and-pasted into a text file or Terminal as necessary.
The whole process so far has assumed that you will use Pandoc flavoured markdown, which has excellent and thorough documentation – this is by far the best markdown for academic writing, mainly because of its excellent citation support.
Install Pandoc and download the appropriate csl file for your preferred citation style to somewhere sensible.
3.Write your work in pandoc-flavoured markdown.
4.a (optional, OSX only) It’s possible (quite easy) to set up the excellent Marked 2 app with pandoc as a processor (you can choose the processor in Marked’s preferences). It requires a short bash script to call the pandoc command, since marked seems to struggle with arguments. You can make the script executable with a
chmod +x and set it as Marked’s processor in the preferences. An example script would be thus, if you replace the CAPS with your own data (assuming you use
~/.pandoc/ as your repository for the above ‘useful little files’):
1 2 3
This, along with marked’s ability to watch a scrivener file, gives you a live preview of your document. I have created a clear, academic-ish style for marked (called, unimaginatively, Academia.css) which you can download from the Marked style repository
Export your scrivener document as plain text markdown (
MYPROJECT.txt) – i.e. not using any of the markdown conversion options etc. since we’re already writing everything in markdown anyway – and use a pandoc command to convert it into a filetype of your choice, eg.
pandoc -s -S --normalize --bibliography ~/.pandoc/YOUR_BIBLIOGRAPHY.bib --csl ~/.pandoc/YOUR_CITATION_STYLE.csl -f markdown -t docx -o MYPROJECT.docx MYPROJECT.txt
This command would create a full document including any headers, footers or markup needed (
-s ), apply smart typography such as curly quotes (
-S ), conflate any consecutive formatting elements etc. to provide neater output (
--normalize ), use the bibliography (
--bibliography ) and citation style (
--csl ) specified, and convert from (
-f ) markdown to (
-t ) docx, with the output as a file (
-o ) called
This is just jargon for a way of writing that can be interpreted easily by a machine.↩
It’s actually a fair bit more complicated than this, with several competing types of markdown. The one I’m going to talk about most here is Pandoc, since this is the one most suited to academics. This is not a coincidence, since it’s a professor of philosophy who wrote the syntax and the program to interpret it.↩
There are also applications specifically for editing Markdown, such as MarkdownPad (Windows), Markdown Pro (Mac) and Markable.in (Online), but once you get to grip with Markdown, these tend to feel a little unnecessary, and have the added disadvantage of not really getting on with Pandoc’s more advanced features such as citations and line-blocks.↩
There are countless resources available, but take a look at fairly exhaustive Pandoc User Manual, and the useful and informative Pandoc Demos. I’ll hopefully follow up this post with a more practical introduction to Markdown syntax, Pandoc style.↩
~is a universal symbol for your home directory, which is where Terminal.app will always start. Some basic knowledge of the terminal is probably necessary for getting through this short tutorial. There’s an excellent introduction here which covers everything you need to know to get started.↩