Appendix C — Quorse Notes Overview Presentation

During the presentation (optional): Get a free github account, install git or GitHub desktop, and open RStudio or VSCodeThis workshop is being recorded.

Author
Affiliation

Dr. Devan Becker

Wilfrid Laurier University

Published

eCOTS Workshop June 07, 2024

C.1 Introduction

Overview

  • These are slides… or are they?

If you’re reading this, the answer is no! This is a portion that is only visible when compiled as a book!

This book chapter created from a slideshow will introduce the basic workflow and some ideas. (Check the source code for this paragraph).

It will be helpful to have a GitHub account, GitHub desktop installed, and RStudio/VSCode running.

Workflow Preview

Once everything is set up:

  • Make slides (or adapt from elsewhere)
  • Add in participation activities
  • Do some live demonstrations in class
  • Push to GitHub after class
    • Everything is now available to the students on a website

Main Benefits

  • Open source and reproducible
  • Easy to use, searchable book for students including all information from class
  • Only one extra step on top of Quarto slides!

C.2 Introduction to Quarto

qmd versus Rmd

If you rename myfile.Rmd to myfile.qmd, it works exactly the same.

qmd is the next generation of RMarkdown.

  • More code options
  • More output options
  • More language options (python, julia, lua, etc.)
  • More editor options

The General Quarto Idea

One input file, many outputs.

  • Accepts qmd, Rmd, and ipynb as input files
  • Outputs to pdf, html, docx, pptx, md, epub, odt, etc.

Code and Prose

This is text. The following is R code.

```{r}
#| eval: false
print("This is R code, but it won't be executed,")
```

Here’s some more text.

```{r}
#| eval: true
print("This is R code, and it will be executed,")
```
[1] "This is R code, and it will be executed,"

Math, too!

Basic math works in all output formats:

$$
ma^{th} = f(un)
$$

\[ ma^{th} = f(un) \]

So Much More!

  • Code line numbering, with line highlight.
  • Interactive elements (shiny, runnable code, ).
  • Non-linear slideshows.
  • So much more!

C.3 Setup Steps

The YAML files

YAML: Yet Another Markup Language

  • Basically, human-readable files that tell a computer what to do.
  • You’ve seen this syntax if you’ve used RMarkdown!
author: "Dr. Devan Becker"
date: "last-modified"
date-format: "iso"

execute:
    warning: false
    cache: true

YAML Separation

_quarto.yml

date-fromat: iso
...

execute:
  warning: false
  ...

profile:
  group:
  - [slides, book]

_quarto-slides.yml

project:
  output-dir: Slides

format: 
  beamer:
    ...
    execute:
      echo: false
      ...

_quarto-book.yml

project:
  type: book
  output-dir: docs
book:
  title: "Quarto Course Notes"
  ...
  chapters:
    - index.qmd
    ...

format:
  html:
    ...
  • The _quarto.yml file includes options that apply to everything.
    • The profile group indicates that slides are the default.
  • The other two have specific options for slides and book, respectively.

Special Things in quarto-book.yml

  • Links to the github repo.
  • Page headers and footers.
  • Navigation options.
  • Chapters (separated into parts) and appendices.
  • Themes/appearance

GitHub Pages Workflow

  • In _quarto-slides.yml, send the outputs whereever
    • I have a folder called “Slides”, so I use project: output-dir: Slides
  • In quarto-book.yml, send the outputs to a folder called “docs”
    • It must be called docs for this to work.
  • On GitHub, go to Settings -> Pages
    • Choose “Deploy from a branch”
    • Choose “main” and “docs”

Anytime you push to the repo, the html files made by quarto are built into a website!

  • Must “build” the html files locally.

Alternative Workflows

  • Github pages, but use a different branch
    • Adds some complexity, but allows the source files to be private.
  • Any static site host
    • Set output-dir to any folder that gets pushed to the website.
    • Useful if you already have a web host set up.

C.4 Authoring

Some Conveniences

  • Custom beamer definitions for spacing in slides
    • \lspace (list space) is a newline in slides, nothing in book.
    • \pspace (paragraph space) is a whitespace character in slides, nothing in book
  • Snippets in RStudio
    • book-only and not-book, but also LaTeX symbols

Conditional Rendering

  • These are slides… or are they?
::: {.content-visible when-profile="slides"}
If you're reading this, then yes they are!!!
:::

::: {.content-visible when-profile="book"}
If you're reading this, the answer is no! This is a portion that is only
visible when compiled as a book!
:::

RStudio snippets make these really easy!

Previewing

With the given setup, Cmd + Shift + K will build the slides (not book).

To see the book you can either:

  1. Run quarto preview --profile book in the terminal
    • Quarto will update as you edit!
  2. Change the default profile briefly, then change it back.

C.5 Summary

qmd files

  • Include code, math, pictures, etc.
  • Render to slides for class.
    • Control what’s included.
  • Render to an online book.
    • Include extra content and capabilities.
    • Hosted publicly for free!
  • Add class discussion points, make available where the students expect it.

Write once, publish anyywhere!

Limitations

  • Stop making new materials!
    • Search for open source or previous materials, edit for your style!
  • It’s always tempting to use the fancy new hotness - be careful!
    • More features = less future proof.
  • If you use my template, you’re bound to open source!
    • You can change it substantially and change the license, but the repo is bound to Sharealike.