Over-engineering Your Thesis with Nix, Pandoc and make
If you find yourself sitting in front of your computer, more or less eager to start writing your Bachelor, Master or PhD thesis and just want a nice, slightly over-engineered template to start: don’t look any further.
It can be built using Nix. Installing all dependencies and producing the final PDF is a matter of running
nix build github:pascalj/thesis-template. If you fork the repository, just adjust the latter part. If you want to build it locally, just use
nix buildand the output will be in
It takes Pandoc Markdown as input. That makes drafting the text a breeze and should you ever need LaTeX primitives, just write it in the Markdown file. Pandoc will pass it through to
pdflatexand it will work as expected. There’s an example in
All images are kept as original as possible: for example, generating a graph from a DOT file is done as a build step. That means that you just have to edit the
make) and the thesis PDF is updated. Out-of-the-box it supports several image formats:
- For PNG no conversion is needed.
- SVG images are converted with Inkscape to the special PDF+TeX format that allows all text inside images to be rendered by pdflatex.
- DOT files are converted and included as PDFs.
- Python scripts that generate LaTeX output are seamlessly integrated.
- Generating beautiful graphs with R, ggplot2 and the tidyverse are automatically created with
tikzDevicefor easy and sharp inclusion into the thesis. I like to keep the logs of my measurements in the repository along with a scripts to create graphs and the build process takes care of the rest. That makes changes very easy.
There are examples for all of these in the document.
It supports citations and references out of the box by the magic of
pandoc-crossref. For example adding
as you can see in [@fig:svg]will be resolved to
as you can see in fig. 1in the final document and a bibliography is supported out-of-the-box.
There are some minor tweaks, for example a
thesis.tex – that is technically not needed – is kept in the repository.
This file has each sentence in its own line to make diffing easier.
Usage and Customization
Depending on what the goal is, there are a few places to make changes:
defaults.yamlis the place to change (command line) options for Pandoc (see Defaults files).
thesis.yamlcontains meta data about the Pandoc document and some options like the title. For example if you want to include extra LaTeX packages, have a look at that file.
template.texcontains the (almost vanilla) Pandoc LaTeX template. If the version breaks (which it doesn’t – thanks Nix), you can generate a new one with
pandoc -D latex > template.tex.
flake.nixallows you to add dependencies.
The content of the thesis should be placed inside the
src/ directory as Markdown files. All images can be placed into
img/<format> directory, so they will be converted autmatically.
- For setting up LaTeX documents with Nix, see the excellent guide at flyx.org.
- The Nix language in general is useful to understand.
- Pandoc’s rather elaborate documentation is recommended.
Should you choose not to build the template with Nix, you need to have the following software installed:
- A LaTeX distribution
- Pandoc with
- latexmk and GNU Make
- Inkscape for converting SVG
- Graphviz for convertig DOT graphs
- Python if you want to create images with Python
- R and tikzDevice if you want to create images with R