Gonzalo Garcia-Castro

So I submitted my thesis (🎉). As anticipated, the submission process was frustrating—this is a canonical event. Though, it was less of a pain thanks Quarto, which took care of the formatting. I spent a considerable amount of time preparing this template, which was a risky move, given the tight schedule I was on¹, but it paid off in the end.

¹ I wrote 80% of my thesis in less than two months, depite having been working for five years on my PhD, I am embarrased to confess. Luckily, the rest of the time was wisely spent in other projects.

In this post, I describe how the upfthesis Quarto template works, and perhaps more importantly, how it can be adjusted to align with the dissertation format required by other universities. First, take a look at how it looks once rendered [link here, in case it does not show up]:

The format

UPF currently requires the following sections, according to the guidelines listed by Guies BibTIC:

Cover: provided by the university, to be requested as a ticket (through CAU)²
Title page
Dedication (optional)
Acknowledgements (optional)
Abstract (English and Catalan)
Preface
Table of contents
List of figures (optional)
List of templates (optional)
Body of the thesis
Bibliography
Glossary (optional)

² Mind that they take from two to five working days to send it over.

The guide also specifies the accepted formats (A4 or B5), fonts (Times New Roman, Arial, or Garamond), font size, and margins. Whenever possible, the upfthesis extension allows the user to choose between the options. Since my LaTeX skills are limited, I constrained some other options for convenience, but help is welcome making the template more flexible.

The main workhorse behind the upfthesis template is the Quarto books format, to which I added some tweaks adjust to the required format taking advantage of the LaTeX template offered by the secretariat. In addition, I used some LaTeX packages to define useful functions (I’ll dig into this later).

The default output format of the upfthesis template is a PDF (upfthesis-pdf), which is the end product required by the thesis secretatiat. It is also possible to render the dissertation in Microsoft Word format (upfthesis-docx), Open Document format (upfthesis-odt), and HTML (upfthesis-html). While the upfthesis output in .docx and .odt formats is not submission-ready yet (word in progress), I found it useful for having my supervisor adding comments and for tracking changes across versions. The HTML format might be useful for publishing the dissertation as a website (work in progress).

Installing ⬇️

This extension requires Quarto to be 1.3.0 or higher. I also recommend an updated version of MikTeX complications during compilation.

quarto use template gongcastro/upfthesis

This will install the extension and create an set up the structure of the project. Take a look at the source code in the GitHub repository . If you are used to working from RStudio, I recommend you create a new RStudio project in the same folder.

Template structure 📁

The downloaded directory contains several sub-directories and files:

_thesis: contains the rendered thesis dissertation in whichever formats you have specified (e.g., thesis.pdf, thesis.docx)
_quarto.yml: this is a YAML file with the global settings of the thesis. Here you can change the title, authors, department, etc. You can change most settings as indicated in the Book Options section of the Quarto reference. Some of these settings are internally set in the _extension.yml file; feel free to change them if you know what you are doing.
chapters/ contains the Quarto (.qmd) files with the body of the thesis. Each section embedded in a different file. The chapters included are based on the Theses: Parts and content section of the Guies BibTIC UPF website. Some of these sections might not be required. If so, you may keep them from being included in the rendered output by removing them from the _quarto.yml file (chapters:) section. For example, here I am commenting out the Glossary section, which is not required:

chapters:
  - index.qmd
  - chapters/01-introduction.qmd
  - chapters/02-chapter-1.qmd
  - chapters/03-chapter-2.qmd
  - chapters/04-discussion.qmd
  - chapters/05-bibliography.qmd
  #- chapters/06-glossary.qmd

Note that the numeric prefix in each .qmd file is only there for convenience: the order in which the files appear in the rendered output is determined by the order in which they appear in chapters:. Also, you may place these files wherever you want in the directory (e.g., in the base directory), as long as you indicate their right paths in chapters:.

img/ contains some images included in the example template. I personally find it more convenient to store all figures in a folder like this). Note that the .qmd files will look for the images (and any other refered resource) in the same folder they are located. In this template repository, the .qmd files are locating in the chapters/ folder, so images are found in the parent directory using double dots ../img/image.png.

💡 You may create as many folders as you find convenient to store files that will be used in your dissertation. The img/ folder is one of those folders you may delete or rename. Just remember to change the file paths referring to the affected files accordingly.

index.qmd is an empty Quarto document that must be present in the main directory. Do not move or rename it. Any content inside this document will be rendered as a separate chapter right after the Table of Contents, which is usually not what one wants.This file must also be listed in chapters: in the _quarto.yml file.
references.bib contains the BibTex references of the thesis. I you are using a reference manager (I strongly recommend using Zotero) you can export you library and replace this file with you desired references. You can also introduce you references manually in BibTex format (e.g., by copy-pasting them from Google Scholar). If you have more tha one .bib document or your .bib document is named differently, you can do the appropriate changes in the _quarto.yml file. For instance, this is how you can indicate more than one .bib file:

bibliography:
  - references.bib
  - other-references.bib

.gitignore: if you are a Git users, you might find this file convenient to avoid committing unwanted documents to your Git history.
apa.csl contains the code necessary to format the citations and bibliography in APA style. You may replace this file by whichever other style you find convenient by replacing apa.csl with the corresponding file from the citation-style-language repository. Remember to change the path in _quarto.yml if necessary.

Using the template 🚀

To render your dissertation to a PDF, you can use the Quarto command line in your console (Command Prompt/Power Shell in Windows, Terminal in MacOS, and command line in Linux):

quarto render

This will render the thesis in PDF and Word formats by default. You can control in which format the theris is rendered this way:

quarto render --to upfthesis-pdf

If you don’t want to render the thesis is either document ever, you can change the default behaviour in the _quarto.yml file, by changing:

format:
  upfthesis-pdf: default
  upfthesis-docx: default

To:

format:
  upfthesis-pdf: default

Tricks and comments 💡

Horizontal pages: this template defines the \blandscape and \elandscape commands (from the lscape LaTeX package) to flip pages to landscape mode. This wway some figures or tables may take more space and be easier to read. This is especially convenient for B5 format.
Logo in colour: To use the logo in colour, just replace the logo.png file in the main directory with the official logo in colour.
Low-level sections: for some reason, I have not been able to add section headers lower than 5 (e.g., 6, 7). I recommend reducing the number of sub-sections. This is issue is currently open (#7) and help is appreciated.

Reuse

CC BY 4.0

Citation

BibTeX citation:

@online{garcia-castro2024,
  author = {Garcia-Castro, Gonzalo},
  title = {Upfthesis: A {Quarto} Template for Thesis Dissertations at
    {UPF}},
  date = {2024-01-10},
  langid = {en}
}

For attribution, please cite this work as:

Garcia-Castro, G. (2024, January 10). upfthesis: a Quarto template for thesis dissertations at UPF.

--- title: "upfthesis: a Quarto template for thesis dissertations at UPF" description: "I wrote my thesis dissertation in Quarto, using a custom template. Here I illustrate how it works and some tips." image: upfthesis.png categories: - r - quarto - thesis - book - pdf format: html from: markdown+emoji code-fold: true reference-location: margin fig-align: center fig-dpi: 600 echo: false warning: false message: false date: 2024-01-10 --- ![](upfthesis.png){width=80% fig-align=center} So I submitted my thesis (:tada:). As anticipated, the submission process was frustrating---this is a canonical event. Though, it was less of a pain thanks **Quarto**, which took care of the formatting. I spent a considerable amount of time preparing this template, which was a risky move, given the tight schedule I was on^[I wrote 80% of my thesis in less than two months, depite having been working for five years on my PhD, I am embarrased to confess. Luckily, the rest of the time was wisely spent in other projects.], but it paid off in the end. In this post, I describe how the *upfthesis* Quarto template works, and perhaps more importantly, how it can be adjusted to align with the dissertation format required by other universities. First, take a look at how it looks once rendered [[link here]([here](https://github.com/gongcastro/upfthesis/blob/main/_thesis/thesis.pdf):), in case it does not show up]: {{< pdf thesis.pdf width=100% height=800 >}} ## The format UPF currently requires the following **sections**, according to the guidelines listed by [Guies BibTIC](https://guiesbibtic.upf.edu/tesis/eng/description): - Cover: provided by the university, to be requested as a ticket (through CAU)^[Mind that they take from two to five working days to send it over.] - Title page - Dedication (optional) - Acknowledgements (optional) - Abstract (English and Catalan) - Preface - Table of contents - List of figures (optional) - List of templates (optional) - Body of the thesis - Bibliography - Glossary (optional) The guide also specifies the accepted formats (A4 or B5), fonts (Times New Roman, Arial, or Garamond), font size, and margins. Whenever possible, the *upfthesis* extension allows the user to choose between the options. Since my LaTeX skills are limited, I constrained some other options for convenience, but help is welcome making the template more flexible. The main workhorse behind the *upfthesis* template is the **[Quarto books](https://quarto.org/docs/books/)** format, to which I added some tweaks adjust to the required format taking advantage of the **[LaTeX template](https://guiesbibtic.upf.edu/ld.php?content_id=31967549)** offered by the secretariat. In addition, I used some LaTeX packages to define useful functions (I'll dig into this later). The default output format of the *upfthesis* template is a PDF (`upfthesis-pdf`), which is the end product required by the thesis secretatiat. It is also possible to render the dissertation in Microsoft Word format (`upfthesis-docx`), Open Document format (`upfthesis-odt`), and HTML (`upfthesis-html`). While the *upfthesis* output in `.docx` and `.odt` formats is not submission-ready yet (word in progress), I found it useful for having my supervisor adding comments and for tracking changes across versions. The HTML format might be useful for publishing the dissertation as a website (work in progress). ## Installing :arrow_down: This extension requires [Quarto](https://quarto.org/docs/get-started/) to be 1.3.0 or higher. I also recommend an updated version of [MikTeX](https://miktex.org/howto/install-miktex) complications during compilation. ```bash quarto use template gongcastro/upfthesis ``` This will install the extension and create an set up the structure of the project. Take a look at the **source code** in the [GitHub repository {{< fa brands github >}}]([**upfthesis**](https://github.com/gongcastro/upfthesis)). If you are used to working from RStudio, I recommend you create a new RStudio project in the same folder. ## Template structure :file_folder: The downloaded directory contains several sub-directories and files: * [_thesis](https://github.com/gongcastro/upfthesis/blob/main/_thesis/): contains the rendered thesis dissertation in whichever formats you have specified (e.g., [thesis.pdf](https://github.com/gongcastro/upfthesis/blob/main/_thesis/thesis.pdf), [thesis.docx](_thesis/thesis.docx)) * [_quarto.yml](https://github.com/gongcastro/upfthesis/blob/main/_quarto.yml): this is a YAML file with the global settings of the thesis. Here you can change the title, authors, department, etc. You can change most settings as indicated in the [Book Options](https://quarto.org/docs/reference/projects/books.html) section of the Quarto reference. Some of these settings are internally set in the [_extension.yml](https://github.com/gongcastro/upfthesis/blob/main/_extensions/gongcastro/upfthesis/_extension.yml) file; feel free to change them if you know what you are doing. * [chapters/](https://github.com/gongcastro/upfthesis/blob/main/chapters/) contains the Quarto (`.qmd`) files with the body of the thesis. Each section embedded in a different file. The chapters included are based on the [Theses: Parts and content](https://guiesbibtic.upf.edu/tesis/eng/parts) section of the [Guies BibTIC UPF](https://guiesbibtic.upf.edu/tesis/eng/parts) website. Some of these sections might not be required. If so, you may keep them from being included in the rendered output by removing them from the [_quarto.yml](https://github.com/gongcastro/upfthesis/blob/main/_quarto.yml) file (`chapters:`) section. For example, here I am commenting out the *Glossary* section, which is not required: ```yaml chapters: - index.qmd - chapters/01-introduction.qmd - chapters/02-chapter-1.qmd - chapters/03-chapter-2.qmd - chapters/04-discussion.qmd - chapters/05-bibliography.qmd #- chapters/06-glossary.qmd ``` > Note that the numeric prefix in each `.qmd` file is only there for convenience: the order in which the files appear in the rendered output is determined by the order in which they appear in `chapters:`. Also, you may place these files wherever you want in the directory (e.g., in the base directory), as long as you indicate their right paths in `chapters:`. * [img/](https://github.com/gongcastro/upfthesis/blob/main/img/) contains some images included in the example template. I personally find it more convenient to store all figures in a folder like this). Note that the `.qmd` files will look for the images (and any other refered resource) in the same folder they are located. In this template repository, the `.qmd` files are locating in the `chapters/` folder, so images are found in the parent directory using double dots `../img/image.png`. > :bulb: You may create as many folders as you find convenient to store files that will be used in your dissertation. The img/ folder is one of those folders you may delete or rename. Just remember to change the file paths referring to the affected files accordingly. * [index.qmd](https://github.com/gongcastro/upfthesis/blob/main/index.qmd) is an empty Quarto document that *must* be present in the main directory. Do not move or rename it. Any content inside this document will be rendered as a separate chapter right after the Table of Contents, which is usually not what one wants.This file must also be listed in `chapters:` in the `_quarto.yml` file. * [references.bib](https://github.com/gongcastro/upfthesis/blob/main/references.bib) contains the BibTex references of the thesis. I you are using a reference manager (I strongly recommend using Zotero) you can export you library and replace this file with you desired references. You can also introduce you references manually in BibTex format (e.g., by copy-pasting them from Google Scholar). If you have more tha one `.bib` document or your `.bib` document is named differently, you can do the appropriate changes in the `_quarto.yml` file. For instance, this is how you can indicate more than one `.bib` file: ```yaml bibliography: - references.bib - other-references.bib ``` * [.gitignore](https://github.com/gongcastro/upfthesis/blob/main/.gitignore): if you are a Git users, you might find this file convenient to avoid committing unwanted documents to your Git history. * [apa.csl](https://github.com/gongcastro/upfthesis/blob/main/apa.csl) contains the code necessary to format the citations and bibliography in APA style. You may replace this file by whichever other style you find convenient by replacing [apa.csl](https://github.com/gongcastro/upfthesis/blob/main/apa.csl) with the corresponding file from the [citation-style-language](https://github.com/citation-style-language/styles/blob/master/apa.csl) repository. Remember to change the path in [_quarto.yml](_quarto.yml) if necessary. ## Using the template :rocket: To render your dissertation to a PDF, you can use the Quarto command line in your console (Command Prompt/Power Shell in Windows, Terminal in MacOS, and command line in Linux): ```bash quarto render ``` This will render the thesis in PDF and Word formats by default. You can control in which format the theris is rendered this way: ```bash quarto render --to upfthesis-pdf ``` If you don't want to render the thesis is either document ever, you can change the default behaviour in the `_quarto.yml` file, by changing: ```yaml format: upfthesis-pdf: default upfthesis-docx: default ``` To: ```yaml format: upfthesis-pdf: default ``` ## Tricks and comments :bulb: * **Horizontal pages**: this template defines the `\blandscape` and `\elandscape` commands (from the `lscape` LaTeX package) to flip pages to landscape mode. This wway some figures or tables may take more space and be easier to read. This is especially convenient for B5 format. * **Logo in colour**: To use the logo in colour, just replace the `logo.png` file in the main directory with the official [logo](https://www.upf.edu/web/marca/desc-marca) in colour. * **Low-level sections**: for some reason, I have not been able to add section headers lower than 5 (e.g., 6, 7). I recommend reducing the number of sub-sections. This is issue is currently open ([#7](https://github.com/gongcastro/upfthesis/issues/7)) and help is appreciated. ## Related extensions Some folks have alreafy provided more generic templates for thesis dissertations, or have developed an extension for their specifc university. Take a look at them for inspiration for customising your own, or for learning nice tricks. Here are some of them, together with some blog posts in covering the topic. * [quarto-thesis](https://github.com/nmfs-opensci/quarto-thesis) by nmfs-opensci * [Enough Markdown to Write a Thesis](https://biostats-r.github.io/biostats/quarto/) by Richard J Telford * [Writing a dissertation in Quarto](https://blog.posertinlab.com/posts/2023-06-09-writing-a-dissertation-in-quarto/) by rich Posert * [Some Quarto PDF formatting tips, with particular reference to thesis writing](https://cameronpatrick.com/post/2023/07/quarto-thesis-formatting/) * [Monash Quarto Template](https://robjhyndman.com/hyndsight/quarto_templates.html) by Rob J Hyndman