Over-engineering Your Thesis with Nix, Pandoc and make

January 2023

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.

You might want to have a look at github.com/pascalj/thesis-template and the output thesis.pdf. It comes with a few nice features:

1. 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 build and the output will be in ./result/thesis.pdf. Easy!

2. 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 pdflatex and it will work as expected. There’s an example in src/chapter_1.md.

3. 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 .dot file, run nix build (or 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 tikzDevice for 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.

4. 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. 1 in 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.yaml is the place to change (command line) options for Pandoc (see Defaults files).
• thesis.yaml contains 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.tex contains 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.nix allows 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 the corresponding img/<format> directory, so they will be converted autmatically.

Resources

• 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.

Dependencies

Should you choose not to build the template with Nix, you need to have the following software installed:

• A LaTeX distribution
• Pandoc with pandoc-citeproc and pandoc-fignum.
• latexmk and GNU Make

Optional:

• 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