🚀  Learning Objectives

By the end of this tutorial, you will be able to:

  • Explain the purpose of Quarto.
  • Create and render your own Quarto Markdown (.qmd) files.
  • Apply Markdown essentials for formatting text.
  • State the purpose of code chunks and chunk options.
  • Include image files in your documents.

🤔  What Is Quarto?

Quarto is an open-source authoring framework that seamlessly blends:

  • Text (Markdown)
  • Code (R, Python, SQL, etc.)
  • Output (HTML, PDF, DOCX, slides, books)

This course adopts Quarto because it enables reproducible data visualization from source code.

🆕  Creating a New Quarto Document

In RStudio, go to File → New File → Quarto Document.

➡️  Rendering the Document

🖥️  Rendered HTML

🏗️  Structure of a Quarto File

🧩  Quarto Building Blocks

  • YAML Header
    Metadata (title, author, date, output formats, execution options), placed at the top of the .qmd to configure the document. YAML is the abbreviation of “YAML Ain’t Markup Language.”

  • Code Chunk
    Blocks sandwiched by triple backticks (```) where you write and run R, Python, or other code. The code can be executed upon rendering the document, and the output can be used in the rest of the document.

  • Marked-Up Text
    Narrative written in Markdown (headings, lists, links, emphasis), communicating your data in words.

📝  Marked-Up Text

Quarto uses a simple, portable plain‐text syntax (Markdown) plus code chunks to create fully reproducible documents—unlike traditional WYSIWYG word processors, such as Microsoft Word. Here is a comparison of both approaches:

Markdown Traditional Word Processors
Separated content & formatting Coupled content & formatting
Lightweight plain-text syntax Feature-rich but heavyweight editors
Built-in code block syntax (```) No integration of code syntax
Portable across platforms & editors Portability issues between programs and computers
Plain-text syntax suitable for version control Binary formats hamper version control

✍️  Markdown: Overview of Text Formatting Options

Text Blocks

Inline Text

✍️  Section Headings

Markdown:

# Top-Level Heading
## Second Level
### Third Level
#### Fourth Level
##### Fifth Level
###### Sixth Level

Rendered Output:

📝️  Paragraph and Line Breaks

Paragraphs: Leave a blank line
Line breaks: Put two spaces or \ at the end of a line

Markdown:

This is a paragraph.
It continues on the same line.

This is a new paragraph,  
exhibiting user-defined\
line breaks.

Note that there are two (invisible) spaces after "paragraph, ".

Rendered Output:

This is a paragraph. It continues on the same line.

This is a new paragraph,
exhibiting user-defined
line breaks.

📋  Lists

Unordered lists: Use *, -, or + to create bullet points
Ordered lists: Use numbers or letters followed by a period and space: "1. ", "a. ", etc.

Markdown:

* One item
* Another item

Ordered:

1. First
2. Second
1. Third(!)

Rendered Output:

  • One item
  • Another item

Ordered:

  1. First
  2. Second
  3. Third(!)

💬  Block Quotes

Block quotes: Prefix lines with >

Markdown:

This is a block quote.

> I think, therefore I am.

---René Descartes, 1637

Rendered Output:

This is a block quote.

I think, therefore I am.

—René Descartes, 1637

📣  Emphasized Text: Italics & Boldface

Italics: Wrap text in *…* or _…_
Boldface: Wrap text in **…** or __…__

Markdown:

*Italic text*.
Also _italic_.

**Bold text**.
Also __bold__.

***Bold italics***.
Also ___bold italics___.

Rendered Output:

Italic text. Also italic.

Bold text. Also bold.

Bold italics. Also bold italics.

🔢  Subscripts & Superscripts

Subscript: Wrap text in ~
Superscript: Wrap text in ^

Markdown:

* Subscript: H~2~O  
* Superscript: E = mc^2^

Rendered Output:

  • Subscript: H2O
  • Superscript: E = mc2

💻  Inline Code

Code display: Wrap code in backticks `...`. It is printed but not evaluated.
Code evaluation: Place r after initial backtick to evaluate R code inline.

Markdown:

The code for 1+2+...+10 is `sum(1:10)`.

The value is `r   sum(1:10)`.

Rendered Output:

The code for 1+2+…+10 is sum(1:10).

The value is 55.

📦  Code Chunks: Basics

  1. Place code between triple backticks (```) to create a code chunk.
  2. Specify the language (e.g., {r}, {python}, etc.) after the opening backticks.

Code Chunk:

```{r}
sum(1:10)
```

Rendered Output:

[1] 55

▶️  Previewing Code in RStudio

Note:

  • Modifications of a code chunk will not automatically update the output.
  • Prior to updating, it might be necessary to run all preceding code chunks to ensure that the latest input variables are available.

🏷️  Chunk Labels

It is advisable to label each code chunk, enabling easier debugging and chunk reuse:

```{r}
#| label: sum-from-1-to-10

sum(1:10)
```
[1] 55

You can reuse this code by inserting a blank code chunk with the same label:

```{r}
#| label: sum-from-1-to-10
```
[1] 55

⚙️️  Chunk Options

Example of a code chunk with options:

```{r}
#| label: chunk-option-example
#| eval: false
#| echo: true

sum(1:10)
```
Selection of execution options for code chunks
Option Description
eval Execute the code chunk?
echo Display the source code in the rendered document?
error Display error messages in the rendered document?
message Display messages in the rendered document?
warning Display warnings in the rendered document?
include Include the code in the rendered document?

🖼️  Including Image Files

```{r}
#| label: fig-cartoon
#| fig-cap: "Image by Aye Chan Phyu Sin."
#| out-width: 60%

knitr::include_graphics("images/cartoon.png")
```
Figure 1: Image by Aye Chan Phyu Sin.
  • Use knitr::include_graphics() to include images in your document.
  • For automatic figure numbers, put fig- at the start the label.
  • Use fig-cap to add a caption.
  • Use out-width or out-height to set the size of the image.

🎉  Conclusion

Congratulations! You’ve acquired essential skills for communicating the work of a data scientist using Quarto. You now know how to:

  • Create and structure a .qmd file.
  • Mark up text.
  • Include code chunks.

For more on Quarto’s features and best practices, see the official Quarto Guide.

Week 1: Tutorial