My Markdown thesis
It’s come to the stage in my Master’s where I have to start thinking about writing my thesis. Apart from all the analysis I have to do before I can do that there is also the question of what I am going to use to construct the document itself.
For the last year or so I have been writing using Markdown which is converted to Tex using Pandoc then used to produce a PDF. I have found this a really good way to work combining the speed and clarity of Markdown with the ability to include LaTeX directly when I need extra flexibility. I have been using the Uberdoc tool to set up projects and combine multiple Markdown files but unfortunately it’s not quite flexible enough for a complex document like a thesis.
I wanted to be able to be able to incorporate my Tex, particularly so I could use John Papandriopoulos’ thesis template. Ideally I wanted to build my own tool (probably in Python or Perl) that would manage projects, including git commits, as well as produce statistics but time doesn’t permit so I have ended up with a Make based solution.
The setup allows me to be flexible with how I set up my directory as the whole
project is searched for Markdown files which are converted to LaTeX in a build
directory. The directory structure is flattened at this stage which means I
don’t have to write the full path when including files. Figures are treated
similarly and there are folders for additional LaTeX files (such as styles and
templates) and bibliography files. I also have a core Tex file which is used to
tie everything together. The PDF is constructed using
latexmk and I can use
texcount for keeping track of my word count.
So when I run
make for the first time the following steps occur:
- The build directory is created with the necessary subdirectories.
- The project directory is searched for Markdown files which are converted to TeX files in the build directory.
- TeX files are copied from the template directory to the build directory.
- All files are copied from the style directory to a style subdirectory inside the build directory.
- All files are copied from the bibliography directory to a bibliography subdirectory inside the build directory.
- The figures directory is searched for image files which are copied to a figures subdirectory inside the build directory.
latexmkis used to build the output file in the build directory.
- The output PDF is copied to the main directory.
It’s not perfect, for example there is a bug that means
make needs to be run
more than once when you add a new file which isn’t ideal, but it mostly does
what I want and hopefully it will get me through. If you want to check it out
the code is available on