Writing an article in LaTeX produces crisp, quality documents and beautiful equations. However, it’s not very user friendly. Recently I’ve been using another language, Markdown, because I find it more readable and intuitive, but it still has LaTeX equation support. To me that’s the best of both worlds. So how about writing an entire PhD thesis in Markdown? This post shows you how.

• Quick link to repository which allows this

Update: Thesis was submitted in October 2018, and is now approved!

This month I’ve started writing up my PhD research into a thesis. One question I was asked was: will you use LaTeX or Word? Word is simple and is easy for others to review, but people who’ve put a lot of figures, sections and equations into a Word file understand how slow and unstable it gets. Sometimes a whole file freezes or gets corrupted. That’s stress I don’t need right now.

Because of this, a lot of scientists use LaTeX. It uses plain-text files with little overhead and allows version control backup with Git. It also supports writing complex equations, cross-referencing and bibliographies. But I don’t think it’s a language that is intuitive or very easy to read, especially since I’ve learnt Markdown for writing this blog. So let’s compare LaTeX and Markdown.

This is how a LaTeX document looks with headings, citations, links and labelled equations:

This is how the same information looks in Markdown:

Markdown is clearly easier to read and write. So I wondered, is it possible to write my thesis in Markdown?

It is, thanks to the hard word of people including John MacFarlane (for writing Pandoc) and Tom Pollard (for writing a framework for a thesis style document).

With the right framework, a series of input Markdown files (say, per chapter) can be combined into a single output file while automatically creating a table of contents, a bibliography, and with dynamic referencing to sections and equations.

It’s not without a few hiccups, as it’s using Markdown in a way it wasn’t designed. But so far I’ve been able to get around problems by falling back to LaTeX input when required.

So let’s take a look at what the Markdown output above looks like.

The outputs

The thing I like most about this system is that I can type either:

• make pdf
• make html or
• make docx

and in less than a second, I get either a LaTeX pdf, html or a Word docx:

LaTeX pdf:

html:

Word:

I think that’s beautiful, especially since one of my supervisors prefers to review in Word. If you want more fine tuning for your LaTeX documents, you can also output to .tex, make your changes, then output to pdf. Great!

So, I’ve taken the work of others and adapted it for my needs, including the formatting requirements of UNSW Sydney where I’ll be submitting my thesis. I’ve also added a few extra capabilities like equation numbering and a word count.

Wordcount

One thing I wanted was a way to track the number of words in the input files.

The first file I need is wordcount.sh, a shell script that interrogates the committed Git files. It’s adapted from on the work of Bastian Rieck.

The second file is plot_wordcount.py, a simple python script which plots your progress like this:

If you want to use the framework, clone my Github repository here.