Quarto as a great teaching tool

Marie-Hélène Burle

April 3, 2023


frontlogo

Markup & markdown

Markup languages

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

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}

Markup languages

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

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…)

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

Previous example using Pandoc’s Markdown:

---
title: My title
author: My name
date: 2022-11-24
---
# 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

How it works

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"
format: html
---

Document structure & syntax: front matter

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"
date: "2022-11-24"
execute:
  error: true
  echo: true
format:
  revealjs:
    theme: [default, custom.scss]
    highlight-style: monokai
    code-line-numbers: false
    embed-resources: true
---

Document structure & syntax: text

Written in Pandoc’s extended Markdown

Document structure & syntax: 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

Demo

 Back to talk page

Quarto as a great teaching tool Marie-Hélène Burle April 3, 2023

  1. Slides

  2. Tools

  3. Close
  • Quarto as a great teaching tool
  • Markup & markdown
  • Markup languages
  • Markup languages
  • Markup languages
  • Markdown
  • Markdown
  • Literate programming
  • Literate programming...
  • Quarto
  • How it works
  • How it works
  • Supported languages
  • Document structure & syntax: front matter
  • Document structure & syntax: front matter
  • Document structure & syntax: text
  • Document structure & syntax: code blocks
  • Rendering
  • Quarto as a teaching tool
  • General considerations
  • Webpages/websites
  • Advantages of code execution
  • Demo
  • f Fullscreen
  • s Speaker View
  • o Slide Overview
  • e PDF Export Mode
  • r Scroll View Mode
  • ? Keyboard Help