The new R Markdown:

Authoring dynamic scientific documents with Quarto

Marie-Hélène Burle

April 11, 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

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

Some advantages of Quarto

General considerations

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

Some advantages of Quarto

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 copy button
  • Great search functionality
  • Site/pages can be hosted anywhere easily

Some advantages of Quarto

Advantages of code execution

  • People can see code outputs without running code
  • Forces to test every bit of code
  • No need for a complex system linking code scripts with publishing documents

Resources

Official sites

Website
Repo
Documentation index

Installation

You can find information in the Quarto documentation or in our previous workshop on Quarto

Basic examples

You can find several examples in our previous workshop on Quarto

Live demo

 Back to webinar page