Tutorial: Hello, Quarto

TipR or Python?

You can work through this tutorial using R or Python code examples. Select your preferred language:

R

Python

Overview

Positron comes ready to work with Quarto out-of-the-box — it includes both the Quarto command line interface and the Quarto VS Code extension.

In this tutorial, you’ll learn how to use Positron with Quarto. You’ll edit code and markdown in Positron and preview the rendered document in the Viewer pane as you work.

Basic Workflow

Here’s what it might look like in Positron to edit and preview a Quarto document:

R

Python

The Quarto document (.qmd) on the left contains a combination of markdown and executable code cells. It is rendered into the HTML version you see on the right. You could also choose to render it into other formats like PDF, MS Word, etc.

This is the basic model for Quarto publishing—take a source document that combines code and narrative, and render it to a variety of output formats.

Setup

If you would like to follow along with this tutorial in your own environment, follow the steps outlined below.

R

1. Be sure that you have installed the tidyverse and palmerpenguins packages:

   install.packages("tidyverse")
   install.packages("palmerpenguins")

2. Download the Quarto document (.qmd) below, open it in Positron.

   Download hello.qmd

Python

1. Be sure that you have installed the jupyter, plotnine and palmerpenguins packages:

   pip install jupyter plotnine palmerpenguins

2. Download the Quarto document (.qmd) below, open it in Positron.

   Download hello.qmd

Rendering

We’ll start out by rendering the example (hello.qmd). To render and preview the document, execute the Quarto: Preview command. You can alternatively use the keyboard shortcut , or the Preview button () in the editor toolbar:

Quarto will render the document, and the rendered output will preview in the Viewer pane. This side-by-side preview works for HTML and PDF outputs. Other formats, like MS Word, will open externally.

The preview will update whenever you rerun the Quarto: Preview command. If you prefer to automatically render whenever you save, you can check the Render on Save option on the editor toolbar.

When rendering, Quarto generates a new file that contains selected text, code, and results from the .qmd file. The new file can be an HTML, PDF, MS Word document, presentation, website, book, interactive document, or other format.

Authoring

Let’s turn our attention to the contents of our Quarto document. The file contains three types of content: a YAML header, code cells, and markdown text.

YAML header

At the top of the file are document level options specified using YAML demarcated by three dashes (---) on either end.

---
title: "Hello, Quarto"
format: html
---

When rendered, the title, "Hello, Quarto", will appear at the top of the rendered document with a larger font size than the rest of the document. The format field denotes that the output should be rendered to the html format.

The basic syntax of YAML uses key-value pairs in the format key: value. Other YAML fields commonly found in headers of documents include metadata like author, subtitle, date as well as customization options like theme, fontcolor, fig-width, etc. You can find out about all available YAML fields for HTML documents here. The available YAML fields vary based on document format, e.g., see here for YAML fields for PDF documents and here for MS Word.

Code cells

Code cells contain executable code to be run during render, with the output (and optionally the code) included in the rendered document.

R

Code cells are identified with {r} with (optional) chunk options, in YAML style, identified by #| at the beginning of the line.

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(palmerpenguins)
```

Python

Code cells are identified with {python} with (optional) chunk options, in YAML style, identified by #| at the beginning of the line.

```{python}
#| label: load-packages
#| include: false

from plotnine import *
from palmerpenguins import load_penguins

penguins = load_penguins()
```

In this case, the label of the code chunk is load-packages, and we set include to false to indicate that we don’t want the chunk itself or any of its outputs in the rendered documents. There are a wide variety of code cell options you can apply to tailor your output. We’ll delve into these options in the next tutorial.

In addition to rendering the complete document to view the results of code cells, you can also run each code cell interactively. Use the command: Quarto: Run Cell, the keyboard shortcut (), or click Run Cell directly above the cell in the Editor.

R

Python

Positron executes the code in the Console and displays the results.

Markdown text

Narrative content is written using markdown. For example, the following markdown text includes a section heading (##) and a link to the Quarto website:

## Meet Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

Quarto supports markdown syntax for basic text formatting, tables, and images, as well as advanced features like citations, cross-references, and equations.

How it works

R

When you render a Quarto document, first knitr executes all of the code cells and creates a new markdown (.md) document, which includes the code and its output.

The markdown file generated is then processed by pandoc, which creates the finished format.

Python

When you render a Quarto document, first jupyter executes all of the code cells and creates a new markdown (.md) document, which includes the code and its output.

The markdown file generated is then processed by pandoc, which creates the finished format.

Next Up

You now know the basics of creating and authoring Quarto documents. The following tutorials explore Quarto in more depth:

• Tutorial: Computations — Learn how to tailor the behavior and output of executable code blocks.

• Tutorial: Authoring — Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout.