Oxforddown

A template for writing an Oxford University thesis in R Markdown. The template uses the bookdown R package together with the OxThesis LaTeX template, plus lots of inspiration from thesisdown.

Sample PDF output: docs/_main.pdf
Sample BS4 book output: ulyngs.github.io/oxforddown/

Examples of theses written with oxforddown:

Ulysses in Cyberspace: Examining the Effectiveness of Design Patterns for Digital Self-Control by Ulrik Lyngs
Teens, Screens and Wellbeing: An Improved Approach by Amy Orben

NOTE: If you've used this template to write your thesis, drop me a line at ulrik.lyngs@cs.ox.ac.uk and I'll add a link showcasing it!

How to cite

@misc{lyngsOxforddown2019,
  author = {Lyngs, Ulrik},
  title = {oxforddown: An Oxford University Thesis Template for R Markdown},
  year = {2019},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/ulyngs/oxforddown}},
  doi = {10.5281/zenodo.3484682},
}

Video tutorials

NOTE: as per v2.0, the introduction chapter no longer needs to be named _introduction.Rmd! Apart from this, the videos should still be mostly right!

See the video tutorials for how to use the template:

For how to write your content with the R Markdown syntax, read through the sample content.

Requirements

R and RStudio version 1.2 or higher
The R packages rmarkdown, bookdown, tidyverse, kableExtra, and here

a LaTeX installation

Option 1: Use TinyTeX (a minimal LaTeX installation intended for use with R Markdown)

the development version of TinyTex is currently required. Install from R with

remotes::install_github('yihui/tinytex')
tinytex::install_tinytex()

Then install the LaTeX packages used by oxforddown (diskspace taken up by TinyTex with the required packages installed is about 280 Mb)

missing_packages <- c(
  "appendix", "babel-english", "babel-greek", "babel-latin", 
  "biber", "biblatex", "caption", "cbfonts-fd", "colortbl", "csquotes", 
  "enumitem", "environ", "eso-pic", "fancyhdr", "greek-fontenc", 
  "grfext", "hyphen-greek", "hyphen-latin", "lineno", "logreq", 
  "makecell", "microtype", "minitoc", "multirow", "notoccite", 
  "oberdiek", "pdflscape", "pdfpages", "quotchap", "soul", "tabu", 
  "threeparttable", "threeparttablex", "titlesec", "tocbibind", 
  "trimspaces", "ulem", "units", "utopia", "varwidth", "wrapfig"
  )
tinytex::tlmgr_install(missing_packages)

Option 2: Use an ordinary LaTeX distribution
- Mac: download and install MacTeX from tug.org/mactex/ (~4 gigs)
- Windows: download and install MikTex from miktex.org

If on Mac
- Command line developer tools. If you haven't got these installed already, your mac will probably automatically prompt you to install them. Otherwise, you can install them by opening a terminal and typing xcode-select --install
If on Windows
- The 'Build all' button is set up to use a program called make to build the pdf output and automatically clean up all the weird files LaTeX generates in the process.
- make can be tricky to install on Windows, so the route of least pain on Windows is to instead build the thesis by knitting index.Rmd or running bookdown::render_book("index.Rmd", output_format = "bookdown::pdf_book") in the R console (the only drawback is that this does not clean up many of the files generated by LaTeX when building the thesis).
If you still want to use 'make', here's how:
Option 1 (quite painful):
- (i) download the minGW installer from https://sourceforge.net/projects/mingw/,
- (ii) open the MinGW Installation Manager, check the box next to mingw32-base and select 'Mark for installation'
- (iii) click 'Installation' then 'Apply changes'
- (iv) make a copy of the file 'mingw32-make.exe' which you will probably find in the folder C:\MinGW\bin\, and name it make.exe
- (v) include this in your environment variables, by opening a terminal / command prompt and typing set PATH=C:\MinGW\bin;%PATH%
Option 2 (supposedly less painful):
- (i) install the package manager chocolatey from here
- (ii) open a command prompt and type choco install make

How to use

download the ulyngs/oxforddown repo as a zip
open oxforddown.Rproj in RStudio

Writing your thesis

update the YAML header (the stuff at the top between '---') in index.Rmd with your name, college, etc.
write the individual chapters as .Rmd files in the root folder
write the front matter (abstract, acknowledgements, abbreviations) and back matter (appendices) by adjusting the .Rmd files in the front-and-back-matter/ folder
for abbreviations, change front-and-back-matter/abbreviations.tex to fit your needs (follow the LaTeX syntax in there)

.Rmd files you don't want included in the body text must be given file names that begin with an underscore (e.g. front-and-back-matter/_abstract.Rmd and front-and-back-matter/_acknowledgements.Rmd). (Alternatively, specify manually in _bookdown.yml which files should be merged into the body text.)

Building your entire thesis

PDF output

options
- Option 1, using make: type 'make pdf' in the terminal (not the R console!) or click 'Build All' on the 'Build' tab
- Option 2, using the knit button: knit the index.Rmd file
- Option 3, using an explicit R command: run bookdown::render_book("index.Rmd", output_format = "bookdown::pdf_book") in the R console
the compiled PDF is saved as docs/_main.pdf

Gitbook output

options
- Option 1, *using make: in the terminal tab (not the R console!), type make gitbook
- Option 2, using an explicit R command: run bookdown::render_book("index.Rmd", output_format = "bookdown::gitbook") in the R console
the set of HTML files for the gitbook are stored in the docs/ folder, and the front page (docs/index.html) is opened in a browser
(Note that if you want to deploy your thesis as a gitbook on GitHub Pages, there must be a .nojekyll file in the docs/ folder, otherwise GitHub does some voodoo that causes some filepaths not to work - if building with make, this file is automatically generated by oxforddown)

BS4 book output

the bs4 book output requires the downlit and bslib R packages (you can install them with install.packages)
options
- Option 1, using make: in the terminal tab, type make bs4book
- Option 2, using an explicit R command: run bookdown::render_book("index.Rmd", output_format = "bookdown::gitbook") in the R console
the set of HTML files are stored in the docs/ folder, and (for option 1) the front page (docs/index.html) is opened in a browser

Word output

options
- Option 1, using make: in the terminal tab, type 'make word'
- Option 2, using an explicit R command: run bookdown::render_book("index.Rmd", output_format = "bookdown::word_document2") in the R console
the compiled MS Word document is saved as docs/_main.docx

The Word output has no templates behind it, and many things do not work (e.g. image rotation, highlighting corrections). I encourage pull requests that optimise the Word output, e.g. by using tools from the officer package.

Building a single chapter

To knit an individual chapter without compiling the entire thesis:

open the .Rmd file of a chapter
add a YAML header specifying the output format(s) (e.g. bookdown::word_document2 for a word document you might want to upload to Google Docs for feedback from collaborators)
Click the knit button (the output file is then saved in the root folder)

As shown in the sample chapters' YAML headers, to output a single chapter to PDF, use:

output:
  bookdown::pdf_document2:
    template: templates/brief_template.tex
    citation_package: biblatex
documentclass: book
bibliography: references.bib

brief_template.tex formats the chapter in the OxThesis style but without including the front matter (table of contents, abstract, etc).

(Also, if you do not set the option citation_package: biblatex, which tell R Markdown to use BibLaTeX, you will get the error "! LaTeX Error: Environment CSLReferences undefined.")

Cleaning up generated auxiliary files

When you build to PDF via make, the auxillary files will be automatically be removed (to adjust how this is done, edit Makefile).
To clean them up manually, run file.remove(list.files(pattern = "*.(log|mtc|maf|aux|bcf|lof|lot|out|toc)"), here::here("front-and-back-matter", "abbreviations.aux")) in the R console.

To clean up files generated when knitting individual chapters, type 'make clean-knits' in the terminal. Or, if you're on Windows without make available, run the command file.remove(list.files(pattern = "*.(log|mtc|maf|aux|bcf|lof|lot|out|toc)"), here::here("front-and-back-matter", "abbreviations.aux")).

Customisations and extensions

for some of the common things you might want to do in your thesis, read through the sample content
for example, the 'Customisations and extensions' chapter (thanks @bmvandoren!) adds tips on how to include PDF pages from a published typeset article in your thesis, and more!

Limitations

Gotchas

don't use underscores (_) in your YAML front matter or code chunk labels! (underscores have special meaning in LaTeX, so therefore you are likely to get an error, cf. https://yihui.org/en/2018/03/space-pain/)
- bad YAML: bibliography: bib_final.bib
- good YAML: bibliography: bib-final.bib
- bad chunk label: {r my_plot}
- good chunk label: {r my-plot}
if you want to deploy the gitbook via GitHub pages, then the /docs folder must contain a file called .nojekyll

Output formats

at the moment only PDF and HTML output have been properly implemented; I may improve on the Word output further down the line

Enjoy!

zavud/oxforddown

Contents