Sharing and Remixing content across Revealjs slides with Quarto Includes

I recently ran a Slidecraft show-and-tell session as part of a weekly Hacky Hour meetup for the NUMBATS research group in my department¹. The idea was for everyone to share something slide related like:

• Slide design tips, tricks and/or opinions,
• Slide-related problems that need solving,
• Quarto slide customisations or features.

I talked about how I used Quarto features to share metadata and content across slides for a multi-day Quarto for Economists workshop I recently taught. This post is a longer, more documented version of what I discussed.

Types of Includes

A few ways exist to include and reuse existing content in Quarto HTML documents (e.g., webpages and Revealjs slides). I won’t explain in detail how these features work, but the footnotes include links to the relevant sections in the official Quarto documentation:

• Share YAML config options between .qmd files using Project and Directory metadata files or the metadata-files: YAML option.²
• Include the contents of code scripts as executable code chunks using the #| file: cell option.³
• Include contents from any text file at specific points in a .qmd file using the {{< include >}} shortcode.⁴
• Include the contents of code scripts, verbatim, as syntax-highlighted read-only code blocks using the include-code-files extension.⁵
• Include the contents of another file, verbatim, at pre-defined locations using the include-in-header:, include-before-body: and include-after-body: YAML options.⁶

The workshop had four sessions, with three content modules and a wrap-up within each session. It was my first time running this workshop, so I knew I’d probably need to update content for later sessions and move modules between sessions based on how the first day went. I used a combination of these features to:

• harmonise Revealjs slide options and features across all content modules and,
• easily update each session’s wrap-up slides using content from within each module folder

I also used the include-code-files extension to include STATA scripts in Quarto documents as part of the workshop content, but I won’t go into that here.

Project structure

I used the following Quarto project structure for the workshop website and materials:

.
├── index.qmd
├── about.qmd
...LICENSE,README.md,references.bib...
├── 01a-hello-quarto
│   ├── images
│   ├── _wrap-up.qmd
│   ├── index.qmd
│   └── slides.qmd
...01b/...01c/...
├── 01d-wrap-up
│   ├── _session-plan.qmd
│   ├── index.qmd
│   └── slides.qmd
...02a/...04d/...
├── _quarto.yml
├── _slides.yml
├── _slides-setup.R
└── style
    └── slides.scss

Every module had its own folder, and I used the XXd-wrap-up folders for session planning notes and summary content. Note that every module had both a website page (index.qmd) and a set of slides (slides.qmd). Here’s the website page for the 01a-hello-quarto module: cynthiahqy.github.io/monash-quarto-aea/01a-hello-quarto/

Includes for slide format and features

The slides for each module were all formatted the same way, with the same Revealjs theme options, slide transitions, slide numbers, etc.. I used the #| file: cell option to include a setup code chunk from the shared _slides-setup.R file:

01a-hello-quarto/slides.qmd

---
title: "Hello Quarto"
subtitle: "Session 1: Getting to know Quarto"
date: 2023-07-18
format: revealjs
metadata-files:
  - ../_slides.yml
---

```{r}
#| label: setup
#| include: false
#| file: ../_slides-setup.R
```

Since all my slides were in different folders, sharing YAML options using the directory metadata file _metadata.yml wasn’t an option. Instead I used the metadata-files: YAML option to share the same _slides.yml file across all of my slides. The only thing I had to be careful about was making sure I got the relative references correct. Even though _slides.yml and the style/ folder were both in the root directory of my repo, I had to use ../style/slides.scss to reference the custom CSS file. This is because the relative links are evaluated from the location of the slides.qmd file (i.e. inside the module folder 01a-hello-quarto/) not the root directory of the repo.

_slides.yml

author: "Cynthia Huang"
footer: "[🔗 cynthiahqy.github.io/monash-quarto-aea](https://cynthiahqy.github.io/monash-quarto-aea)"
format:
  revealjs:
    theme: [default, ../style/slides.scss]
    transition: fade
    slide-number: true
    chalkboard: true
    date-format: full

Another option would have been to include the slide options in the Project metadata file _quarto.yml. One advantage of using the metadata-files: option is that you could potentially use multiple sets of metadata for different groups of slides within the same project (e.g. if you had different presenters for different modules).

_quarto.yml

project:
  output-dir: _output

metadata-files:
  - _slides.yml

In addition to sharing YAML options, I also used a shared setup R script across all my slides. I used it to load the {countdown} package to insert countdown timers, but you could include other setup tasks too.

_slides-setup.R

# set width of code output
options(width = 65)

# load packages
library(countdown)

Includes for wrap-up slides

At the end of each session, I showed summary slides with key takeaways from each module. I used the {{< include >}} shortcode to pull in the content from each module’s _wrap-up.qmd file:

01d-wrap-up/slides.qmd

---
title: "Wrap-Up"
subtitle: "Session 1: Getting to Know Quarto"
date: 2023-07-18
format: revealjs
metadata-files:
  - ../_slides.yml
---

{{< include ../01a-hello-quarto/_wrap-up.qmd >}}

{{< include ../01b-formats/_wrap-up.qmd >}}

{{< include ../01c-articles/_wrap-up.qmd >}}

# Before lunch...

## Questions

::: task
Any questions / anything you'd like to review or learn before we wrap up the workshop?
:::

::: task
Suggestions / requests for things to cover in Thursday's session?
:::

This setup allowed me to move modules between sessions easily and ensured the wrap-up slides were always up-to-date with any content changes within modules.

Final rendered slides

Here’s the rendered version of the 01d-wrap-up/slides.qmd file shown above:

You can find the rest of the workshop content and slides here: cynthiahqy.github.io/monash-quarto-aea. All the source files for the workshop content are also available in this repo: github.com/cynthiahqy/monash-quarto-aea

Footnotes

1. NUMBATS is the Non-Uniform Monash Business Analytics Team in the Department of Econometrics and Business Statistics at Monash Business School. See this website for more.

2. See Shared Metadata

3. See Code Cells: Knitr > Include

4. See content and code examples

5. See quarto-ext/include-code-files

6. See HTML example and LaTex example