Marco Sciaini

Replacing LaTeX with Pandoc and Markdown

11 Jul 2015

I started with LaTeX quite some time ago, but now, for my Master's thesis, I wanted to go simpler. Plus, I would like to have a simple conversion in a .docx format to share the work with colleagues for revision, which is not that easy with plain TeX. Two tools came in my mind when I thought of this: markdown and pandoc.

I am already using markdown for this blog and for reports with rmarkdown in R. I am familiar with pandoc to export map widgets from rleaflet and for report conversion from markdown to pdf, docx, html and so on. Therefore, I started looking on the web for templates that I could use for this.

There are a few out there, in particular:

... and of course, the best one:

Based on his framework and the inspiration of the others I mentioned before I created my own Markdown+Pandoc workflow to write my thesis and convert it in various formats. I thought I would put my workflow and example template out here, in case anyone is searching for how to write their own thesis in Markdown+Pandoc.

Why Pandoc and Markdown?

Pandoc is this haskell library that makes miracles of text happen.
Got a .docx and need .tex? Done.
Got a .md and need .epub? Sure that.
Got a .tex and need Reveal.js slides? No problem.
Pandoc is able to do all of these things—easy-peasy-lemon-squeezy.

Lincon Mullen from Profhacker has written a nice introduction to Markdown, and why geeks love it. I will quote him here for the basics:

"[...] is a great format to use because (1) it can be read by any computer or device; (2) it’s future proof, since computers will always be able to read it; (3) it can be synced to all your devices; (4) it can be converted to virtually any format."

Imma install all this…

... and assuming you are Debian/Ubuntu.

Pandoc:

wget https://github.com/jgm/pandoc/releases/download/1.15.0.5/pandoc-1.15.0.5-1-amd64.deb &&
ar p pandoc-1.15.0.5-1-amd64.deb data.tar.gz | tar zx

... for PDF export we also need LaTeX:

wget http://mirror.selfnet.de/tex-archive/systems/texlive/Images/texlive2015-20150523.iso
sudo mkdir /mnt/texlive2015
sudo mount -o loop /path/to/texlive2015-20150523.iso /mnt/texlive2015
cd /mnt/texlive2015
sudo ./install-tl

We choose a full installation and create the textfile /etc/profile.d/texlive.sh afterwards with the following content:

export PATH=/usr/local/texlive/2015/bin/x86_64-linux:$PATH
export MANPATH=/usr/local/texlive/2015/texmf-dist/doc/man:$MANPATH
export INFOPATH=/usr/local/texlive/2015/texmf-dist/doc/info:$INFOPATH

We need python for Tom Pollards framework:

sudo apt-get install python python3

At last, a good text editor is missing. I think Sublime 3 is a decent option for this. It offers many Markdown related packages, code completion, nice themes, [insert random awesomeness] and most important: Distraction free mode, essential for writing a thesis and not spending too much time on the interweb.

sudo add-apt-repository ppa:webupd8team/sublime-text-3
sudo apt-get update
sudo apt-get install sublime-text-installer

Changes to phdthesismarkdown

As I mentioned before, I built this template on the framework of Tom Pollard. Most changes I've made to it concern the layout of the PDF export. I've made minimal changes to the makefile to improve the PDF export (IMHO).

I will invest some time in the future to improve the docx export, when I find the time.

Preview the final (example) result here.

Workflow

First

Clone my repository onto your local computer (or download the Zip file).

Second

Third

... done. Very convenient, isn't it?

Fourth

If you consider to change the layout of the PDF export the following files are relevant for you:

Conclusion

It is a really enjoyable workflow to write a thesis this way. I am hoping that this will make future collaboration in writing a little bit easier, without switching to Word. The style is a wild mix of layouts I used in the past years for my term papers and could easily be adapted. If you have any suggestions on how to adapt it, let me know.