README.md

NOTE Major change: To build the thesis, you now simply knit index.Rmd - see details below.

Contents

• Requirements
• Video tutorials
• How to use
  • Writing your thesis
  • Building your entire thesis
    • PDF output
    • Gitbook output
    • BS4 book output
    • Word output
  • Building a single chapter
  • Cleaning up generated auxiliary files
• Customisations and extensions
• Limitations
  • Gotchas
  • Output formats

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
• Sample BS4 book output

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
• Interpreting Neural Language Models for Linguistic Complexity Assessment by Gabriele Sarti

NOTE: If you've used this template to write your thesis, drop me a line at [email protected] 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:

1. as per v3.0, building the entire thesis is done by knitting index.Rmd
2. as per v2.0, the introduction chapter no longer needs to be named _introduction.Rmd

Keeping these changes in mind, the videos should still be informative:

• Part 1: Building the entire thesis
• Part 2: Building a single chapter
• Part 3: Understanding the file structure
• Part 4: A walk-through example of creating your thesis
• Part 5: The content included in index.Rmd (or: why the introduction chapter is special)
• Part 6: Adjusting the order of chapters
• Part 7: _bookdown.yml: Adjusting build settings
• Part 8: Makefile: Adjusting build settings
• Part 9: The LaTeX templates

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

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

• You build the entire thesis by opening index.Rmd and clicking the 'knit' button.
• The generated thesis files are saved in the docs/ folder
• To choose between output formats, go to the top of the YAML header and edit the line thesis_formats <- "pdf"; to the format(s) you want (the options are "pdf", "bs4", "gitbook", and "word")
• You can build to multiple formats simultaneously with, e.g., thesis_formats <- c("pdf", "bs4", "word")
• If you want to customise the build function, edit scripts_and_filters/knit-functions.R

PDF output

knit: (function(input, ...) {
    thesis_formats <- "pdf";
    ...

BS4 book output (HTML)

knit: (function(input, ...) {
    thesis_formats <- "bs4";
    ...

• NOTE: the bs4 book output requires the downlit and bslib R packages (install them with install.packages)
• Note also that to deploy a BS4 book 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. This file is generated automatically by oxforddowns knitting function.

Gitbook output (HTML)

knit: (function(input, ...) {
    thesis_formats <- "gitbook";
    ...

• Note that to deploy 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. This file is generated automatically by oxforddowns knitting function.

Word output

knit: (function(input, ...) {
    thesis_formats <- "word";
    ...

• Note that 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:

1. open the .Rmd file of a chapter
2. 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)
3. 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 e.g.:

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

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

Cleaning up generated auxiliary files

When building to PDF, Latex generates a whole bunch of auxillary files - these are automatically removed by the custom knit function.

To change how this is done, edit scripts_and_filters/knit-functions.R.

Customisations and extensions

• for some 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 much 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!