Quarto as a great teaching tool

Author

Marie-Hélène Burle

Content from the talk slides for easier browsing.

Markup & markdown

Markup languages

  • Control the formatting of text documents
  • Powerful but the unrendered text is visually cluttered and hard to read

Example: Tex—often with macro package LaTeX—to create pdfs

\documentclass{article}
\title{My title}
\author{My name}
\usepackage{datetime}
\newdate{date}{24}{11}{2022}
\date{\displaydate{date}}
\begin{document}
 \maketitle
 \section{First section}
 Some text in the first section.
\end{document}

Example: HTML—often with css/scss files—to create webpages

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>My title</title>
    <address class="author">My name</address>
    <input type="date" value="2022-11-24" />
  </head>
  <h1>First section</h1>
  <body>
    Some text in the first section.
  </body>
</html>

Markdown

  • Removes the visual clutter and makes texts readable prior to rendering
  • Created in 2004
  • By now quasi-ubiquitous
  • Initially created for webpages
  • Raw HTML can be inserted when easy syntax falls short

Pandoc’s extended Markdown

Pandoc (free and open-source markup formats converter) supports an extended Markdown syntax with functionality for figures, tables, callout blocks, LaTeX equations, citations…

Remains as readable as basic Markdown, but can be rendered in any format (pdf, books, entire websites, Word documents…)

  • Removes the visual clutter and makes texts readable prior to rendering
  • Created in 2004
  • By now quasi-ubiquitous
  • Initially created for webpages
  • Raw HTML can be inserted when easy syntax falls short

Previous example using Pandoc’s Markdown:

---
title: My title
author: My name
---
# First section
Some text in the first section.

Literate programming

Literate programming is a methodology that combines snippets of code and written text.

First introduced in 1984, this approach to the creation of documents has truly exploded in popularity in recent years thanks to the development of new tools such as R Markdown and, later, Jupyter notebooks

Quarto

Website
Repo
Documentation index

How it works

Code blocks are executed by Jupyter (Python or Julia) or knitr (R), then pandoc renders the document into any format

Julia/Python:

noshadow From Quarto documentation

R:

noshadow From Quarto documentation

Code blocks are executed by Jupyter (Python or Julia) or knitr (R), then pandoc renders the document into any format

Can be used from .qmd text files or directly from RStudio or Jupyter notebooks.

Supported languages

Syntax highlighting in pretty much any language

Executable code blocks in Python, R, Julia, Observable JS

Output formats

- HTML
- PDF
- MS Word
- OpenOffice
- ePub
- Revealjs
- PowerPoint
- Beamer
- GitHub Markdown
- CommonMark
- Hugo
- Docusaurus
- Markua
- MediaWiki
- DokuWiki
- ZimWiki
- Jira Wiki
- XWiki
- JATS
- Jupyter
- ConTeXt
- RTF
- reST
- AsciiDoc
- Org-Mode
- Muse
- GNU
- Groff

Document structure & syntax

Front matter

Written in YAML
Sets the options for the document. Let’s see a few examples.

Can be very basic:

---
title: "My title"
author: "My name"
---

Written in YAML
Sets the options for the document. Let’s see a few examples.

Or more sophisticated:

---
title: "Some title"
subtitle: "Some subtitle"
institute: "Simon Fraser University"
---

Text

Written in Pandoc’s extended Markdown

Code blocks

Syntax highlighting only:

{.language} code

Syntax highlighting and code execution:

```{language}
code
```

Options can be added to individual blocks:

```{language}
#| option: value

code
```

Rendering

Two commands:

quarto render file.qmd    # Renders the document
quarto preview file.qmd   # Displays a live preview

Quarto as a teaching tool

General considerations

  • Extremely well documented
  • Solid team behind the work
  • Free and open source
  • Uses only well established and well tested tools

Webpages/websites

  • Fast, easy, and clean
  • Sites work on screens of any size out of the box (uses Bootstrap 5)
  • Can be customized with CSS/SCSS, but good out of the box
  • Code blocks can have a little copy button
  • Site/pages can be hosted anywhere easily

Advantages of code execution

  • People can see the output without running the code
  • Forces to test every bit of code
  • If the code broke when giving an old workshop, prevents the embarrassment of discovering it in the middle of a live demo
  • No need for a complex system linking code scripts with teaching documents