Quarto Basics

With Quarto, creating documents and reports becomes a breeze. In this chapter, you will learn how to set up Quarto, explore its key features, and start creating your own quarto documents with ease.

What is Quarto?

Quarto is a free, open-source system that helps you create interactive and reproducible documents easily.

Literate programming combines code and documentation in a single, readable document. Before delving into the basics of Quarto, it may be worthwhile to know the brief history of its predecessors.

Sweave

Sweave was one of the first tools for literate programming in R, allowing users to embed R code in LaTeX documents, combining R’s statistical power with LaTeX’s typesetting.

R Markdown

R Markdown is a modern alternative to Sweave, enabling the integration of text and R code in various output formats like HTML, PDF, and Word, not just LaTeX.

Quarto

Which leads us to Quarto, a new system that enhances the R Markdown ecosystem. Quarto provides a seamless framework for integrating code, text, and visualisations into a single, interactive, and reproducible document.

Quarto Fundamentals

Quarto provides a seamless framework for integrating code, text, and visualisations into a single, interactive, and reproducible document. Written in Markdown, Quarto is easy to learn yet powerful enough for complex document creation.

Quarto: Multi-Language and Multi-Engine

Quarto is not only limited to R code chunks, and you can also use Python, Julia, and SQL code chunks in your Quarto documents.

R Markdown on the other hand is tied to R, and has a dependency and requirement for R.

Quarto also provides a range of built-in templates that you can use to create documents for different purposes, such as academic papers, presentations, and websites. These templates make it easy to get started with Quarto and create professional-looking documents with minimal effort.

Setting Up Quarto

To get started with Quarto, you will need to install Quarto. You can do this by here.

Once you have installed Quarto, you can create a new Quarto document by:

  1. Go to the File menu in RStudio

  2. Select New File > New File > Quarto Document

  1. Choose the document type: Document, Presentation, or Interactive.

A Quarto file is a plain text file with the extension .qmd.

Now that you’ve got your first quarto document up and ready, let’s explore some key components! These include:

  • A YAML header

  • Chunks of R code

  • Markdown text

YAML

When you open up your first quarto document, you will notice a block of text up the top that looks something like this:

This is the YAML header, which contains metadata about your document, including the title, author, and editor. It allows you to edit the document’s title (currently “Untitled”), specifies that the output will be in HTML format, and indicates that the document will open in the visual editor by default.

Source vs Visual Editor

RStudio v1.4 or higher includes Visual Markdown editing. Instead of markdown syntax (e.g., bolding with double asterisks), you can format text, add images and insert tables using a toolbar or keyboard commands, similar to a word processor. View sections 28.3 and 28.4 for more detail.

Beyond the basics, you can add some real handy components to the YAML

author For assignments especially, its good to include your name and potentially student ID with this section in the YAML.
subtitle For reports it may be nice to add a subtitle for further detail.
toc A table of contents can be a useful tool in structuring your document. toc-depth specifies the level of headings to include (e.g. toc-depth: 2 includes the top-level headings and second-level headings in the toc.)
date If you’d like to include the due date or publishing date of the report.
YAML Structure

The structure of a YAML can be a little finicky, and errors may occur if it is not formatted correctly. If you encountering errors or missing components - it may be worthwhile to cross-check. A useful starting point is the Quarto documentation.

R Code Chunks

Code chunks refer to sections in the document where you can write and execute code. These chunks are enclosed by three backticks followed by the name of the language you are using (e.g., r for R code). Code chunks can be included in three ways:

  1. Keyboard commands: Ctrl + Alt + I (Windows) or Cmd + Option + I (Mac)
  2. Clicking the Insert button in the toolbar (top right):

  1. Typing the code chunk manually:

Write the code you want to include within the chunk and when you run it, the output will be displayed directly below the chunk!

Did you know

Code doesn’t have to be in a chunk! You can also include inline code by using backticks (``) around code you would like to run in text.

You can also add options to the code chunk to control how the code is executed and displayed. For example, you can specify the output format, the width and height of plots, and whether the code should be displayed in the output.

Look at the image of the code chunk above, you can see that the chunk has the following options:

fig-cap: This option allows you to add a caption to the figure.

fig-width: This option specifies the width of the figure.

echo: This option controls whether the code in the chunk is displayed in the output.

These are only a couple examples of options for chunk options, and there are many more available. You can find a full list of chunk options in section 28.5.2 as well as further discussion in Communicating with Quarto.

Global Options

To set global options for all code chunks, add them in the YAML header under execute:. Indent the options you want to apply by pressing tab on the next line.

Markdown text

In a Quarto document, you can write text using Markdown syntax. Markdown is a lightweight markup language that allows you to format text using simple and intuitive syntax. You can use Markdown to create headings, lists, links, images, and more.

Headings

Headings are created using the # symbol followed by the heading text. The number of # symbols indicates the level of the heading. For example, # creates a first-level heading, ## creates a second-level heading, and so on.

Text Formatting

Just like in any other word processors, you can also format your text. Here are some examples:

  • Bold: **bold** or __bold__
  • Italic: *italic* or _italic_
  • Strikethrough: ~~strikethrough~~
  • Code: `code`

Lists

Lists can be created using *. You can also create nested lists by indenting the items with spaces.

Checklist

You can also create checklists in Quarto! This can be done by using - [ ] for an empty box and - [x] for a checked box.

Rendering Your Document

Once you have written your document, you can render it to see the output. To render your document you can:

  1. click the Render button in the toolbar
  2. use the keyboard shortcut Ctrl + Shift + K (Windows) or Cmd + Shift + K (Mac)
  3. run the quarto::render() function in the console

  1. In the Terminal via quarto render:

When you render your document, Quarto will execute the code chunks and generate the output. The output will be displayed in the Viewer pane in RStudio, and you can also view the output in a web browser by clicking cog icon next to Render and ticking the Preview in window box.

Test your knowledge

** potentially a multiple choice question here about different common chunk options and what they do ??**

** interactive component to edit a basic yaml / include things in yaml – pain point: warnings, messages = false, toc **

Additional Resources

These are the more basic of the quarto markdown syntax. For more on how to communicate with quarto, refer to Communicating with Quarto. Additionally, the following resources may be helpful: