Notes on website/book setup

Showing slides within chapters

I wanted to embed a series of slides for each unit within associated chapters, so that I and students can go to a single “landing page” for each unit. Here are the steps I took to make this possible.

Note that the following steps assume a directory structure as follows:

project-root/
 _quarto.yml
 _metadata.yml
 _build-slides.sh
 styles.scss
 index.qmd
 01-preliminaries/
  overview
   index.qmd
   overview-slides.qmd
  tools
   index.qmd
   tools-slides.qmd

Embedding overview-slides file into overview.qmd

I am using the embedio extension for quarto to embed slides into the landing pages, e.g.

{{< r_evealjs "overview-slides.html">}}
(remove the _, of course...)

I am also using this to embed pdf files into the pages – just replace revealjs above with pdf.

The following text goes into overview.qmd:

<div>

[*Open slides in new tab*](slides.html){target="_blank"}.
  
```{=html}
<iframe class="slide-deck" src="slides.html"></iframe>
```
</div>

Also, we need to define the class slide-deck as follows, within the file styles.scss:

.slide-deck { border: 3px solid #dee2e6; width: 100%; height: 475px; }

Ensuring that *-slides.qmd files are automatically rendered with quarto::quarto_render()

By default, the slides in *-slides.qmd would not automatically be rendered every time the book is rebuilt, so initially I thought I would have to manually render the individual slide decks before rendering the book. But then, I learned that we can make use of quarto’s pre-render option to programatically render all *slides.qmd files into their html equivalents with a simple R script that is run before the quarto build:

to_render <- 
  list.files(recursive = T, pattern = "slides.qmd")

sapply(to_render, quarto::quarto_render)

To ensure that this script is run when the book is rendered, I added _build-slides.r as a pre-render command within the _quarto.yml file:

project:
  type: book
  pre-render: _build-slides.r

Defining yml options that apply to all slides in this project

There were a few slide options that I want to use for all slides made in this project, e.g. I will always use serif as the base theme, I want callout notes to have minimal appearances, etc. To do this, I made a new file _metadata.yml the root level, which included these options.

format:
  revealjs: 
    theme: [serif]
    output-file: "slides" # Note that this ensures all output files are simply named slides.html
    incremental: true
callout-appearance: minimal

(See _metadata.yml for all options so defined.)

I also called on this file within each *-slides.qmd header, for example:

---
title: "Open and reproducible research"
subtitle: "Motivations and tools" 
metadata-files:
  - ../_metadata.yml
---

Changing size of slide deck title

I find the default font size of h1 in the serif theme to be a bit too big, and wanted to redefine this across all slides. I added the following text to the _metadata.yml file defined above:

header-includes:
  - |
    <style>
      .reveal .slides > section:first-child h1 {
        color: #225555;
        font-size: 2em;
      }
    </style>

There is probably a more elegant way to do this, but I am moving on for now.

Deploying the book through Netlify

Deploying the site through Netlify was as easy as connecting my netlify account (which I authenticate with gitlab) to the repository.

The only change I had to make was through Build & Deploy --> Build settings, where I changed the Publish directory to _book.

Connecting the netflify deployment to gklab.org

I purchased the gklab.org domain through Google domains, which is now operated through squarespace. I logged into squarespace (authenticated with my google account) via https://account.squarespace.com/domains.

Here, I went to DNS settings and added a new record. The host name here is rr, type is CNAME, and data is the domain assigned by netlify (*.netlify.app).

Once this was done, I went to the Netlify settings for this site, and navigated to Domain management. Here, I added rr.gklab.org as a “Domain alias” under Production domain.