Using markdown + pandoc to write my biology PhD thesis

The last I ever used Microsoft Word for a thesis was 2007. This thesis worked out to something like 50 pages. After page 30, things started getting ugly. Word crashed regularly, attempts at centering one paragraph led to centering of the entire document (followed by yet another crash). Maybe it was because I just had a sucky Windows laptop then… but on the other hand, the results were also quite ugly! For my Master thesis, I tried to do things a little differently. LaTeX was pretty common in my field and produced really nice typeset documents, but I didn’t want to bother with LaTeX language for symbols and italics and what not. I know it’s probably not that difficult, but it does intrude with the writing process (which is difficult enough as it is!). So in 2008, I turned to LyX for my Master thesis and a couple of grant applications after that. LyX uses LaTeX in the background, and lets you format the final look with LaTeX, but allows you to type in a WYSIWYG document processor. Not too bad an experience.

However, LyX looked a little messy and outdated, and it felt too much like using Word. For my PhD thesis, I wanted to go even simpler (or more complicated, depending how you want to look at it!). My bf introduced me to markdown, and I saw that others had used it for their thesis or papers, and that it was possible to add citations and everything else academics needed, with the help of pandoc. It basically uses the power of LaTex to create your document, but you get to concentrate on writing, in a simple text editor. It looked clean and tidy, and appealed to the procrastinating, typography-loving, tools-and-gadgets geek in me. Or maybe I’m just an academic hipster.

Anyway, even though there are a couple of how-tos already out there (the best one being this), I found that I still had to hack around to get my bibliography and greek-letters to work. So I thought I would put my workflow and example files/template here, in case anyone is searching for how to write their PhD thesis in markdown + pandoc.

Check out the final (example) result


OS: Mac OS X Mavericks

Markdown editor: Mou (free, clean layout, but gets a bit laggy after some time and requires a restart)

Bibliography manager: Papers

LaTeX editor: Sublime Text (for final document typesetting/formatting the pre-amble. I could also have used this for markdown instead of having two separate apps opened, but i couldn’t get markdown syntax highlighting to work here and didn’t want to waste more time figuring that out!)

Backup + versioning + sharing: Dropbox (rest in peace knowing there is one local copy and one in the cloud, and all changes are saved as versions in dropbox!)

PDF builder: pandoc via Terminal


Mou screenshot

Thesis writing in markdown using Mou



Install pandoc and LaTex, and other tools above that you might need.

Download my template/example files, or get them from GitHub.

In Terminal, set the current directory: (Note: Don’t use spaces in your folder or file names!)

cd /Users/chia/Dropbox/ThesisMarkdownPandoc

Then run this pandoc command to build your pdf:

pandoc --latex-engine=xelatex -H preamble.tex -V fontsize=12pt -V documentclass:book -V papersize:a4paper -V classoption:openright --chapters --bibliography=papers.bib --csl="csl/nature.csl" "introduction/" "introduction/" -o "phdthesis.pdf"

If you like how it looks, feel free to use my files and play around. Good luck with thesis writing!

Download the template/example files

The PDF result

14 thoughts on “Using markdown + pandoc to write my biology PhD thesis

  1. Hi, Chia, it’s very beautiful, but it seems the template link (pdf link is ok) was broken …
    Could you please kindly update it or send me a copy ?
    Thanks a lot.

    • Thanks for your tutorial archerimagine! I did try to get Sublime to work with Markdown, but ran into some problems along the way (thought I can’t remember now what the problem was). So I just stuck to Mou at that time so that I could keep working on the thesis writing instead of debugging :p But for the future I would definitely try to get Sublime to work properly with Markdown, and I’m sure your article will help me a lot with that! Mou was nice and clean to work with, but sometimes there was a lot of lag requiring an app restart, so it’s not so ideal for working on a document all day.

      • Thanks for the appreciation, try sublime once, even Mou is great, as a software developer i wanted to use just one editor for my coding and documentation. That is the reason for sublime. i am also trying for my P.Hd so will follow you.

      • hey archerimagine, quite an overdue reply, but i’ve given sublime text a second chance, now that i’m done with PhD work and have some time to learn RoR and what-not for my own interest! some really nice custom configurations with sublime text!!!! good luck with writing up your thesis!

  2. Thanks a lot Chia, you made my day!
    I was trying to figure out how to build a thesis-quality report with markdown and you dropbox repo is full of information. Very nice!

    • Hey Antoine,
      Thanks for your comment and sorry I didn’t get back to you as I was travelling the last few months after my PhD 😀 I hope you’ve been able to figure out markdown reports and have it working well! When I had to print my thesis “properly” a few months after my viva/defence, I was pretty glad to have done it in markdown/pandoc/LaTeX as it was easy to fix-up, format and send for printing and binding. Alternative would have been to write it 100% in LaTeX but for thought-flow, markdown is just much easier. Best of luck with your work!!

  3. Pingback: MultiMarkdown + pandoc + LaTeX (plain text) | (D) Miren Berasategi

  4. How did you use Papers in this workflow?

    I’m asking because as far as I could see, Papers can only *export* to .bib, but not constantly *sync* your library to a .bib. Therefore I found Mendeley to be a better option in the end, although I liked Papers more in some ways. Am I missing something, or did you export manually every time you updated your bibliography in Papers?

    • Hi Gandalf, I’ve forgotten what I did last time as I moved out of academia after graduating 4 years ago. But I suspect I might have been exporting my Papers .bib file each time…. By the time I was writing my thesis, I think I already had most of my sources so I only had to update the .bib file if I needed a new source while writing…

      • Very well. I’ll continue to use Mendeley then, since it’s .bib sync is just too useful, and I also greatly prefer my PDF and references to be in files in the filesystem, rather than in a database format as Papers uses – even if I do greatly prefer the UI and app experience of Papers 🙂

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s