Template for writing a PhD thesis in Markdown

# tompollard/phd_thesis_markdown

Switch branches/tags
Nothing to show

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

## Latest commit

…proc

Fix citations and travis build
7c882bf

## Files

Failed to load latest commit information.
Type
Name
Commit time

# Template for writing a PhD thesis in Markdown

This repository provides a framework for writing a PhD thesis in Markdown. I used the template for my PhD submission to University College London (UCL), but it should be straightforward to adapt suit other universities too.

## Citing the template

If you have used this template in your work, please cite the following publication:

Tom Pollard et al. (2016). Template for writing a PhD thesis in Markdown. Zenodo. http://dx.doi.org/10.5281/zenodo.58490

## Quickstart

If you're a mac user and you have conda and brew installed, run the following in your terminal to install and generate the example outputs:

# get texlive

# update tlmgr and packages
sudo tlmgr update --self

# make python venv and install pandoc
conda create -n phd -y python=3.7 pandoc
conda activate phd

# Install required python and texlive packages
make install

## Why write my thesis in Markdown?

Markdown is a super-friendly plain text format that can be easily converted to a bunch of other formats like PDF, Word and LaTeX. You'll enjoy working in Markdown because:

• it is a clean, plain-text format...
• ...but you can use LaTeX when you need it (for example, in laying out mathematical formula).
• it doesn't suffer from the freezes and crashes that some of us experience when working with large, image-heavy Word documents.
• comments, drafts of text, etc can be added to the document by wrapping them in <!-- -->
• it works well with Git, so keeping backups is straightforward. Just commit the changes and then push them to your repository.
• it is able to take advantage of autocompletion capabilities for figures and citations in several text editors (VSCode, Sublime, etc.)
• there is no lock-in. If you decide that Markdown isn't for you, then just output to Word, or whatever, and continue working in the new format.

## Are there any reasons not to use Markdown?

There are some minor annoyances:

• if you haven't worked with Markdown before then you'll find yourself referring to the style-guide fairly often at first.
• it isn't possible to add a short caption to tables and figures (figures are now fixed, thanks to @martisak). This means that /listoftables includes the long-caption, which probably isn't what you want. If you want to include the list of tables, then you'll need to write it manually.
• the style documents in this framework could be improved. The PDF and HTML (thanks @ArcoMul) outputs are acceptable, but HTML and Word needs work if you plan to output to this format.
• there is no straightforward way of specifying image size in the markdown right now, though this functionality is coming (see: #15) (Image size can now be specified. Thanks to @rudolfbyker for highlighting this).

## How is the template organised?

• Makefile => contains instructions for using Pandoc to produce the final thesis.
• output/ => directory to hold the final version.
• source/ => directory to hold the thesis content. Includes the references.bib file.
• scratch/ => directory to hold tables which can be converted between different formats.
• source/figures/ => directory to hold the figures.
• style/ => directory to hold the style documents.

## How do I get started?

1. Install the following software:
• A text editor, like Sublime, which is what you'll use write the thesis.
• A LaTeX distribution (for example, MacTeX for Mac users).
• Pandoc, for converting the Markdown to the output format of your choice.
• Pandoc plugins by running make install
• Git, for version control.
2. Fork the repository on Github
4. (Skip this step to use default UCL style) Configure style for your institution - see instructions below
5. Navigate to the directory that contains the Makefile and type "make pdf" (or "make html") at the command line to update the PDF (or HTML) in the output directory.
In case of an error (e.g. make: *** [pdf] Error 43), consult this article for possible fixes. Most importantly, make sure tlmgr is properly installed, then run install.sh
6. Edit the files in the 'source' directory, then goto step 5.

## How does it work?

The universal document converter pandoc does all the heavy lifting. For example:

1. make pdf (the code under pdf: ... in Makefile) runs pandoc which takes as input
1. the markdown files which contain the writing content: input/*.md
2. a yaml file with metadata: input/metadata.yml
3. a LaTeX template: style/template.tex
4. a LaTeX header: style/preamble.tex
5. a BibTeX file of your references: input/references.bib
6. a csl style file for citations: style/ref_format.csl
7. a bunch of options which change the output e.g. --number-sections
2. the output produced is:
1. the generated pdf: output/thesis.pdf
2. logs (which contain the .tex which was compiled): pandoc.pdf.log

Put simply, pandoc uses the latex template provided to create a .tex file, then compiles it. In detail, pandoc processes the input files in the following way (the file names in quotes aren't visible to you, but are named for the purpose of understanding):

1. Make replacements within the markdown files input/*.md e.g.:
• references to figures, captions, and sections are handled: @fig:my_fig -> \ref{fig:my_fig}
• equations are converted to LaTeX and numbered: $f(x) = ax^3 + bx^2 + cx + d$ {#eq:my_equation} -> $$f(x) = ax^3 + bx^2 + cx + d\label{eq:my_equation}$$
• citations are handled: [@Cousteau1963] -> (Cousteau Jacques & Dugan James 1963)
• see input/*.md for more examples!
2. Create "body.tex" by:
• converting all the *.md files in the order that they were stated in the pandoc call

# Troubleshooting

1. The first thing to try if the make * command fails is a simpler build, e.g. if make pdf failed, try make tex to see if that fails too.
2. If tex compilation is failing (i.e. make tex works but make pdf fails), try updating tex live and/or packages. For example, if you get the error make: *** [pdf] Error 43, have a look in pandoc.pdf.log for the error. If it is something like
l3backend-xdvipdfmx.def' not found


then try:

sudo tlmgr update --self
sudo tlmgr l3backend
# Full nuclear option - update *all* the packages! (takes about 10m)
# sudo tlmgr update --all
1. Try reinstalling everything from scratch (tip: check out .travis.yml)
2. Search the github issues and pull requests in this repo

# Contributing

Contributions to the template are encouraged! There are lots of things that could be improved, like:

• finding a way to add short captions for the tables, so that the lists of tables can be automatically generated.
• cleaning up the LaTeX templates, which are messy at the moment.
• improving the style of Word and TeX outputs.

Please fork and edit the project, then send a pull request.

Template for writing a PhD thesis in Markdown

## Packages 0

No packages published