How to make a professionally sexy quarto presentation
Quarto is the answer
I didn’t really ‘get’ quarto at first, and a lot of the very cool features of Quarto are still beyond me, but I spent a lot of time getting to grips with it for presentations as part of my posit::conf(2023) talk, and I was really excited by Mine Çetinkaya-Rundel’s talk on the upcoming manuscript feature. Basically, Quarto is a publishing system that integrates code and narrative. If you use R Markdown or Jupyter Notebooks, Quarto is very similar.
TLDR
If you want a rough Edinburgh themed Quarto presentation: check this repository out and use it any way you want.
In this post:
In this post I will go over:
Creating a quarto presentation
Creating a custom .scss file to modify the presentation style
Publishing quickly to github pages.
I’m assuming that you want to make a presentation for a specific event like a conference, etc., and you want to be able to share that easily.
Quarto Presentations are Quarto Projects
The first mistake I made was thinking that a Quarto presentation was one file. At a minimum, you should think of a Quarto presentation as having three files:
The Quarto document (e.g. presentation.qmd) which holds your content
The Quarto .yml (e.g. _quarto.yml) file which configures your files - essentially, this is what lets github easily understand how you want your files presented.
Your custom theme .scss file (e.g. mytheme.scss). Sass (Syntactically Awesome Style Sheets are an upgrade to custom style sheets (.css) files, if you were an old-school Tumblr girlie, or your Powerpoint theme file if you’re a Powerpoint diehard)
If you’re used to working in Powerpoint, this might start to feel really cumbersome. And that’s fair. Powerpoint deals with themes and presentation (and included media like photos, videos, sound, etc.) all within the .pptx extension. You need to do that yourself with Quarto.
While you can create individual Quarto files quickly and easily, just as you would R Markdown files, I’ve come to think of any Quarto file you want to publish as really all being Quarto projects. Quarto projects have a lot of advantages, such as the ‘freeze output’ which is really useful.
Git First or Last?
This is probably one of those occasions where creating your git repository last makes a lot of sense. After all, you’ll probably spend a lot of time playing with your presentation before you’re ready for it to be public, but you can always set your repository to private if you want to create your Git Repository first. I’m going to talk Git First in this case, really just because that’s how I started this morning.
Step 1: Create your git repository
Go to Github, create a new repository. Mark it private if you want to hide your work until you’re ready to share it. I like to add a README and .gitignore with the R template, and then you can check out your repository with your own method of choice. Note your .gitignore will have this:
# pkgdown site
docs/
If you want to publish to github pages, you’ll want to remove this because we want git to have access to the docs folder.
Step 2: Create your quarto presentation project
In your R Studio Project you’ll want to create two files:
A new Quarto document (I went for ed_template.qmd).
- You probably do this via New File > New Quarto Presentation. But if you go for a new Quarto file instead you can simply edit the front matter (the bits at the top marked by ‘—’ so it reads
format: revealjsand it will render in a Quarto presentation instead)
- You probably do this via New File > New Quarto Presentation. But if you go for a new Quarto file instead you can simply edit the front matter (the bits at the top marked by ‘—’ so it reads
A new .yml file
This must be named “_quarto.yml”
You can create this by asking for a new text file - it will become a .yml file after you save it with that extension
Make sure both of these files are in the same directory.
In your _quarto.yml file you need the following:
project:
title: "Your snazzy presentation"
type: website
output-dir: docs
You might put in more later, but this tells Quarto that when it renders the presentation it needs to put everything in a docs folder, which github pages will then present from.
If you render your Quarto presentation now, you’ll see a ‘docs’ folder appear. Your presentation should also open in your browser. Cool, eh?
Now might be a good time to commit your initial changes to your repository and push them.
Step 3: Edit your front matter
Your title slide and a lot of the information displayed by your browser is mostly controlled by the front matter (that’s the parts between the --- symbols at the top). This is a chunk of YAML which provides a lot of information about the document and is really handy in manuscript writing, but that’s probably another blog post. The title slide mainly pulls from this.
Here’s some basic frontmatter that I would normally expect on an Edinburgh slide.
---
title: "A University of Edinburgh Quarto Template"
subtite: "A custom presentation for you to adapt as you see fit"
format:
revealjs:
theme: serif
editor: visual
author:
- name: "Jane Bloggs"
id: jb
orcid: 0000-0000-0000-0001
email: jane.bloggs@ed.ac.uk
affiliation:
- name: Roslin Institute, University of Edinburgh
city: Edinburgh, Scotland
url: www.ed.ac.uk
- name: "Marie McDonald"
id: mm
orcid: 0000-0000-0000-0002
email:
affiliation:
- name: R(D)SVS, University of Edinburgh
city: Edinburgh, Scotland
url: www.ed.ac.uk
logo: /content/rdsvs.png
footer: "Your social media handles - anything you want on each slide"
bibliography: references.bib
---Note there’s two extra files being referenced here by this YAML, /content/rdsvs.png and references.bib. I like having all my media in a content directory (not inside ‘docs’, let Quarto deal with that folder). Put a University approved logo of your choice in there. references.bib is a file in bibtext. For example, my mock bibliography looks like:
@misc{quartoguide23,
author = {Quarto Guide},
year = {2023},
url={https://quarto.org/docs/guide/},
journal={Quarto Guide},
publisher={posit.co}
}
@article{knuth84,
author = {Knuth, Donald E.},
title = {Literate Programming},
year = {1984},
issue_date = {May 1984},
publisher = {Oxford University Press, Inc.},
address = {USA},
volume = {27},
number = {2},
issn = {0010-4620},
url = {https://doi.org/10.1093/comjnl/27.2.97},
doi = {10.1093/comjnl/27.2.97},
journal = {Comput. J.},
month = may,
pages = {97–111},
numpages = {15}
}And if I cite work in my presentation it will all be dealth with automagically. Nice.
Step 4: Write your talk
Now it’s time to create your lovely content!
If you want to know more about what Quarto presentations can do, this ’revealjs format demo has loads of great things you can do, copy the code and make it work for you!
Step 5: Customise your .scss
The final file we want to create is your theme. Do you remember this chunk in our front matter?
format:
revealjs:
theme: serif
So far we’ve been using the serif theme and you can see what the .scss for that looks like here.
You can copy the edtheme.scss wholesale - or make changes to it.
Change the theme to ‘edtheme.scss’ in the frontmatter and render!
format:
revealjs:
theme: edtheme.scss
Publish to github
Once you’re happy with your presentation, commit all your changes, go back to github, go to ‘Settings’.
In ‘Settings’, on the left-hand side menu go to ‘Pages’. You’ll see ‘Build and Deployment’. You want your Source to deploy from a branch, and the Branch to be ‘main’ (or choose another if you like working with branches) and deploy from the ‘docs’ folder.
Your talk will now be hosted on github pages, and the address is something like: https::/[yourgithandle].github.io/[your_repository_name]
Last words
I’ve made my version of the edtheme available on git and I’ll probably tweak it as I go, please feel free to log issues or edit the theme yourself! You may find it goes well with Edinburgh ggplot theme