Quarto Essentials

Bogdan G. Popescu
bogdan.popescu@johncabot.edu

John Cabot University

Introduction

What is Quarto

Quarto - open-source publishing system designed for creating dynamic, reproducible documents, including reports, presentations, and websites.

It supports multiple formats like HTML, PDF, Word, and slides.

Why Use Quarto?

  • Integrates well with R, Python, and Julia.
  • Enables embedding of code chunks directly in documents for dynamic content generation.
  • Facilitates reproducibility by linking code and results seamlessly.

Quarto Document Structure

YAML Header

  • The YAML header defines the document metadata, such as title, author, date, and output format.
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
---

# Introduction

This is an example.

Quarto Document Structure

YAML Header

  • The YAML header defines the document metadata, such as title, author, date, and output format.
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
---

# Introduction

This is an example.

Creating HTML Output

Basic YAML Configuration

To generate an HTML file, specify format: html in the YAML header.

Rendering the Document:

Use quarto render in R to generate the output.

Adding a Table of Contents

Enabling TOC:

  • Add toc: true in the YAML header to automatically generate a table of contents.

  • Control depth with toc-depth (e.g., 2 for two levels of headings).

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
---

# Introduction

This is an example.

Adding a Table of Contents

Customization

  • Rename the title with toc-title: "Contents".
---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

Equations

You can easily add inline equations in the following way

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

Equations

You can easily add inline equations in the following way

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

Equations

You can easily add inline equations in the following way

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

For more advanced equations, check: https://qmd4sci.njtierney.com/math

Code

Embedding Code

This is how we include code in our documents.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r}
summary(mtcars)
```

Code

Embedding Code

This is how we include code in our documents.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=TRUE}
summary(mtcars)
```

Code

Embedding Code

This is how we only include code output in our documents.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=FALSE, eval=TRUE}
summary(mtcars)
```

Code

Embedding Code

This is how we only include code without output in our documents.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

Code

Embedding Code

Many times you might have seen annoying library messages:

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

```{r}
library(dplyr)
```

Code

Embedding Code

To avoid them in printing, you should do:

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

```{r warning=FALSE, message=FALSE}
library(dplyr)
```

Embedding Resources

What is Self-Contained HTML?:

An HTML document that includes all dependencies (images, CSS, JavaScript) within a single file.

Why Use It?

Easy to share and view without requiring external resources.

This means that you will only see an html document being produced.

Embedding Resources

This a complicated document (with formulae, graphs) without resource-embedding.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

```{r}
library(dplyr)
```

Embedding Resources

This a complicated document (with formulae, graphs) with resource-embedding.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
embed-resources: true
---

# Introduction

This is an example.

This is an equation: $E=mc^{2}$

This is also an equation: 

$$E=mc^{2}$$

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

```{r}
library(dplyr)
```

Text Formatting

This is how we format text within our document.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

*This is italic text.*

**This is bold text.**

***This is bold and italic.***

This is reference to a `qmd` document.

Headings

This is how we add headings and subheadings.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

The following are headers:

# Header 2
## Subheader 1
### Sub-subheader 1

Headings

This is how we can automatically number the headers.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
number-sections: true
---

# Introduction

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

The following are headers:

# Header
## Subheader
### Sub-subheader

Headings

This is how we can remove some headers from being numbered.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
number-sections: true
---

# Introduction

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

The following are headers:

# Header
## Subheader {.unnumbered}
### Sub-subheader {.unnumbered}

Headings

This is how we can remove some headers from being numbered and from the Table of Contents

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
number-sections: true
---

# Introduction

```{r echo=TRUE, eval=FALSE}
summary(mtcars)
```

The following are headers:

# Header
## Subheader {.unnumbered .unlisted}
### Sub-subheader {.unnumbered .unlisted}

Pictures

This is how we add pictures.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is how we can include pictures:

![](figures/elephant.png){width="50%"}

Lists

This is how we add lists.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

* unordered list
  + sub-item 1
  + sub-item 2
    - sub-sub-item 1

1. ordered list
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1

Tables

This is how we add tables.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is a table.

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|    12 | 12   | 12      |   12   |
|   123 | 123  | 123     |  123   |
|     1 | 1    | 1       |   1    |

Diagrams

Quarto has native support for embedding Mermaid and Graphviz diagrams.

This enables you to create flowcharts, sequence diagrams, state diagrams.

---
title: "Statistical Analysis Report"
author: "Your Name"
date: "2024-11-05"
format: html
toc: true
toc-title: "Contents"
---

# Introduction

This is a diagram.

```{mermaid}
%%| echo: fenced
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

Videos

You can include videos in documents using the {{< video >}} shortcode. For example, here we embed a YouTube video:

Videos can refer to video files (e.g. MPEG) or can be links to videos published on YouTube, Vimeo, or Brightcove.

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

Callout Blocks

Markdown Syntax

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Output

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

Word Basics

In order to create Word docs you will need to install:

Terminal
quarto tools install chromium

Word Basics

In order to create Word docs you will need to install:

Terminal
quarto tools install chromium

Word Basics

In order to create Word docs you will need to install:

Terminal
quarto tools install chromium

Word Basics

In order to create Word docs you will need to install:

Terminal
quarto tools install chromium

Word Basics

Use the docx format to create MS Word output. For example:

---
title: "My Document"
format:
  docx:
    toc: true
    number-sections: true
    highlight-style: github
---

PDF Basics

Use the pdf format to create PDF output. For example:

---
title: "My document"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

Prerequisites

In order to create PDFs you will need to install a recent distribution of TeX. We recommend the use of TinyTeX (which is based on TexLive), which you can install with the following command:

Terminal
quarto install tinytex

Document Class

Quarto uses KOMA Script document classes by default for PDF documents and books.

For PDF documents this results in the following Pandoc options set by default:

format:
  pdf:
    documentclass: scrartcl
    papersize: letter

You can set documentclass to the standard article, report or book classes.

Note

Setting your documentclass to either book or scrbook will automatically handle many of the common needs for printing and binding PDFs into a physical book.

Output Options

There are numerous options available for customizing PDF output, including:

  • Specifying document classes and their options

  • Including lists of figures and tables

  • Numerous options for customizing fonts and colors.

For example, here we use a few of these options:

Output Options

Here is an example:

---
title: "My Document"
format: 
  pdf: 
    documentclass: report
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    mainfont: Times New Roman
    colorlinks: true
---

Quarto Manuscripts

Quarto manuscript projects provide a framework for writing and publishing scholarly articles.

By using one or more notebooks or .qmd documents as the source of content and computations, computations can be published alongside the manuscript, allowing readers to dive into your code.

It is possible to produce manuscripts in multiple formats (including LaTeX or MS Word)

Quarto Manuscripts

The output of a Quarto manuscript is a website (live example)

Conclusion

There are lots of options for Quarto Documents:

Checkout the Quarto Guide

Most relevant are:

  • Authoring
  • Computations
  • Documents
  • Presentations

Please make sure that your assignments look nice from now on 😄

Popescu (JCU): Quarto Essentials