Oxforddown

A template for writing an Oxford University thesis in R Markdown.

Tutorials and examples

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.

The template uses the bookdown R package together with the OxThesis LaTeX template, plus lots of inspiration from thesisdown.

Examples of theses written with `oxforddown`

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},
}

Requirements

LaTeX - download and install the MacTeX distribution from tug.org/mactex/ (please be aware that it's quite large - 4.1 gigs!)
- Yihui Xie's TinyTeX is sometimes causing trouble - if you normally use TinyTex and can't get oxforddown to work, try installing the package 'cbfonts-fd' with tinytex::tlmgr_install('cbfonts-fd') (as per this issue).
- If you are still stuck, try uninstalling TinyTex with tinytex::uninstall_tinytex(), then install the MacTeX LaTeX distribution and restart RStudio.
R and RStudio version 1.2 or higher
The R packages bookdown, tidyverse, and reticulate (the other packages you need should be automatically installed when you build this project for the first time in RStudio)
(If on a Mac): Command line developer tools. You can install these by typing xcode-select --install in a terminal prompt

Example output

PDF output: see docs/_main.pdf
Gitbook output: see ulyngs.github.io/oxforddown/

Usage

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

Compiling your thesis

PDF output

click 'Build All' on the 'Build' tab or type 'make pdf' in the terminal (not the R console!)
the compiled PDF is saved as docs/_main.pdf, and the PDF is opened

Gitbook output

in the terminal tab (not the R console!), type 'make gitbook'
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
if you want to deploy your thesis as a gitbook on GitHub Pages, then make sure that there's a .nojekyll file in the docs/ folder (otherwise GitHub does some voodoo that causes some paths not to work)

Word output

in the terminal tab (not the R console!), type 'make word'
the compiled MS Word document is saved as docs/_main.docx and opened

The Word output has no template 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.

Writing your thesis

To use this template to write your thesis, do the following:

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 - the introduction chapter must be named _00-introduction.Rmd.
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.)

Knitting individual chapters

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

This will format the chapter in the OxThesis style but without including the front matter (table of contents, abstract, etc)

Cleaning up generated auxiliary files

By default, when you build the entire thesis, the auxillary files will be removed (to adjust how this is done, edit Makefile).

To clean up files generated when knitting individual chapters, type 'make clean-knits' in the terminal.

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 newly added '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!

CODE-BR3AKER/oxforddown