search

tompollard / phd_thesis_markdown

Template for writing a PhD thesis in Markdown
MIT License
1.21k stars 551 forks source link
markdown pandoc thesis-template

readme

Template for writing a PhD thesis in Markdown Build Status

DOI

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

Installation

  1. Install pandoc. This repository requires pandoc 3.1+, so if you install pandoc using a package manager (e.g. apt), check that it meets the version requirement. Otherwise, install by following the link.
  2. Install pandoc-crossref, a pandoc filter for numbering and cross-referencing figures, tables, sections and code blocks.
  3. Install the required TeX packages to enable compilation to PDF.

Quickstart for Mac Users

If you're a Mac user and you have conda and brew installed, run the following in your terminal to install pandoc and TeX packages (steps 1 & 3):

# get texlive
brew install --cask mactex

# 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

Notes for Linux Users

There are several ways to install TeXLive. This guide (written for Ubuntu) may be useful. In short, you can:

  1. Install TeXLive from repositories (for Ubuntu, autocomplete apt install texlive to see all available packages), or;
  2. Install TeXLive manually and use the package manager (tlmgr) to install required packages. If you go down this route, you can run make install to install required TeXLive packages.

Handy references

Should I use this template?

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:

Are there any reasons not to use Markdown?

There are some minor annoyances:

Detailed template information

How is the template organised?

How do I get started?

  1. Install the software outlined above, as well as:
    • A text editor, like Sublime, which is what you'll use write the thesis.
    • Git, for version control.
  2. Fork the repository on Github
  3. Clone the repository onto your local computer (or download the Zip file).
  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:

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} -> \begin{equation}f(x) = ax^3 + bx^2 + cx + d\label{eq:my_equation}\end{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
  3. Create "main.tex" from style/template.tex by running code wrapped in $ signs. The important things to note are:
    • this populates style/template.tex with metadata from input/metadata.yml and the arguments from the pandoc call
    • "body.tex" is pasted in verbatim in place of $body$
  4. Create "references.tex" by converting ./input/references.bib
  5. Concatenate files together to create the final thesis.tex = style/preamble.tex + "main.tex" + "references.tex"
  6. Compile thesis.tex (you can see the logs for this process, and what "thesis.tex" would look like in pandoc.pdf.log)
    • TIP: You can also generate and view output/thesis.tex by running make tex - this follows all the above steps, bar the final compilation

What else do I need to know?

Some useful points, in a random order:

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
  3. Try reinstalling everything from scratch (tip: check out .travis.yml)
  4. 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:

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