11  Quarto

According to the Quarto Website, Quarto is an open-source scientific and technical publishing system, and it is already available on your machines because it is bundled with recent versions of RStudio (version 2022.07 or later).

Quarto is part of a set of tools designed to enhance the reproducibility of your work. Other tools and platforms such as GitHub, Jupyter, Docker, ArXiv, and bioRxiv can facilitate reproducibility in various ways. In this module, we won’t explore the paradigm of reproducible research in detail. Instead, our focus will be on how to use Quarto to make your analyses and reports more appealing, interactive, and efficient.

In this lesson, we’ll weave code and narrative into professionally rendered Quarto documents and use GitHub to safely store, share, and administer our results.

11.1 Set up your work environment

Before creating your first Quarto document, we need to set up the GitHub environment. Originally founded as a platform for software developers, GitHub’s architecture is designed to manage changes made during software development. This architecture is also beneficial for version control of documents or any information collection.

Version control is especially important when working in teams, as it helps synchronize efforts among project participants. However, GitHub is also a reliable and open online platform for individual work, providing change tracking, documentation, and sharing features.

To set up your personal GitHub environment, follow these steps:

  1. Review the Hello-World Section in GitHub’s Quickstart Documentation. Initially, reading it is sufficient—no need to complete the tutorial yet.
  2. Create a GitHub account.
  3. Download and install Git. Git is a distributed VCS (version control system) that mirrors the codebase and its full history on every computer. GitHub is a web-based interface that integrates seamlessly with Git. For a clear explanation of Git’s core concepts, watch this video.
  4. In RStudio (under Tools > Global Options > Git / SVN), check “enable version control” and set the path to git. On Windows: C:\Program Files\Git\bin\git.exe. On macOS/Linux, the path is usually set automatically (e.g., /usr/bin/git or /opt/homebrew/bin/git if installed via Homebrew). After setting the path, restart RStudio.
  5. Create a repository on GitHub. In the tutorial, skip the section ‘Commit your first changes’.
  6. By default, your repository will have one branch named main. Create an additional branch called dev off the main. Follow the instructions in the Hello-World Tutorial for guidance.
Note

For technical issues, please consult the discussion forum.

11.1.1 Tell Git who you are (one-time setup)

Before your first commit, set your identity in the Terminal Tab:

git config --global user.name  "Jane Doe"
git config --global user.email "jane.doe@example.com"

Confirm:

git config --global --list

These values are stored locally and appear in every commit.
They are independent of the token or SSH key you’ll use when pushing.

11.1.2 Authenticating with GitHub

Most “push rejected: authentication failed” errors disappear once you pick one modern login method and finish a short, two-step setup. Password-based Git access was turned off in 2021, so every workflow now relies on either a personal-access token (PAT) carried over HTTPS or an SSH key-pair.

Method 2-step quick-start Good to know
Fine-grained PAT (HTTPS) 1) In GitHub go to Settings > Developer settings > Personal access tokens > Fine-grained tokens > Generate new token.
2) Choose a name, tick the repo permission, set an expiry date, and copy the token. Paste it the first time RStudio asks for a password (your username stays the same).		 Default and simplest—works behind most firewalls; you can scope the token to one repo or organisation; regenerate when it expires (classic PATs are being phased out).
SSH key 1) Run ssh-keygen -t ed25519 -C "you@example.com" and press Enter three times.
2) Copy ~/.ssh/id_ed25519.pub into GitHub under Settings > SSH & GPG keys > New SSH key.		 No tokens to paste; great for scripts and CI; works offline once the key is in your agent; if port 22 is blocked, use ssh.github.com:443.
Git Credential Manager (GCM) Install Git on Windows (bundled) or run brew install --cask git-credential-manager on macOS.
The first push opens a browser login and GCM stores the resulting token in your system keychain automatically.		 Zero copy-pasting; rotates tokens automatically; cross-platform; ideal if you already use Microsoft or GitHub Enterprise SSO.
Note

See or wipe cached secrets anytime via RStudio > Tools > Global Options > Git/SVN > Credentials (on Windows, these are stored in the Credential Manager; on macOS, in the Keychain Access utility).

11.1.3 Switching your remote from HTTPS to SSH

If you cloned over HTTPS but later add a key:

git remote set-url origin git@github.com:<USER>/<REPO>.git

…and vice-versa for HTTPS:

git remote set-url origin https://github.com/<USER>/<REPO>.git

11.1.4 Common troubleshooting checklist

Symptom Fix
fatal: Authentication failed immediately after token paste Token expired or wrong scope; generate a new fine-grained PAT with repo access.
Prompted for credentials on every pull/push Enable credential caching: git config --global credential.helper manager-core (GCM) or store (plain-text fallback).
Permission denied (publickey) with SSH 1) Run ssh -T git@github.com for a verbose test.
2) Make sure the key is in your agent: ssh-add ~/.ssh/id_ed25519.
3) If you’re behind a corporate proxy, add to ~/.ssh/config: Host github.com / Hostname ssh.github.com / Port 443.
Two-factor authentication enabled, PAT works in CLI but RStudio still asks Upgrade to RStudio ≥ 2023.12; older builds ignore macOS/Windows keychain entries.

Once your first push succeeds, Git stores your chosen credentials, and the warnings usually disappear for good.

Need more depth? Jenny Bryan’s Happy Git with R chapter on “Credential caching” walks through platform-specific storage back-ends.

11.2 Create a local clone

Cloning means copying the contents of a GitHub repository (including version history) to your computer, so you can work on it locally in RStudio. To work on your project locally, you need to clone your GitHub repository to your computer. Here’s how:

In RStudio, go to (File > New Project > Version Control > Git).

Use the HTTPS or SSH link from your GitHub repository, depending on which authentication method you’ve configured and select a local directory for the clone. Then click “Create Project”:

Figure 11.1: Clone GitHub Repository

Once you have cloned the online repository, you’ll see the contents of the repository in the Files pane, and a new Git tab will appear in the RStudio interface.

Figure 11.2: New features in RStudio

By default, the repository includes three files:

  1. .gitignore: Specifies intentionally untracked files to ignore.
  2. RStudio Project File (.Rproj): Contains metadata for the RStudio project.
  3. ReadMe File (.md): A markdown file with information about the repository.

The gitignore and .Rproj files are created locally when initializing the project in RStudio. These files may not yet exist on GitHub, depending on how the online repository was set up.

Figure 11.3: Changes in Git tab

Before making further changes, switch to the dev branch:

Figure 11.4: Switch branch

At this point, the dev branch mirrors the main branch.

Note

It is highly recommended to work in progress on a separate developer branch, like dev, and keep the main branch for stable versions. You can later merge changes from dev to main through a pull request (see Opening a Pull Request).

11.3 Creating Your First Quarto Document

Now that the environment is set up, let’s create our first Quarto document.

In RStudio: Navigate to (File > New File > Quarto Document). Enter a title for your document, accept the default settings, click “OK”, and save the file. You’ll receive a sample Quarto file with the extension .qmd.

By default, Quarto is in Visual Editing mode, which provides a WYSIWYM-style editing interface for Quarto documents. Switch to the Source Editor:

Figure 11.5: Switch mode in RStudio

While the Visual Editor interface is more intuitive, the source editor promotes a deeper understanding of underlying structures. Moreover, errors can be spotted and debugged more easily in Source Editor mode.

Quarto gives you two editors:

Mode Best for How to toggle
Visual (WYSIWYM) quick drafting, beginners, content-first writing Click > “Visual”
Source precise Markdown control, debugging chunk options, version-control diffs Click > “Source” (or the same shortcut)

Recommendation: start in Visual if you are new to Markdown, but switch to Source once you need fine-grained control or when preparing a pull-request diff– the raw text makes code reviews and troubleshooting easier.

Quarto documents include three core components. Metadata, text and code:

Figure 11.6: Quarto sample file

Metadata is written in YAML syntax and defines document properties like the title, output format, or creation date.

Exercise

Explore YAML syntax and document properties here.

Insert a suitable parameter in the metadata section of your Quarto document to include today’s date in the document header. Click the Render button in RStudio to generate the HTML output.

    
---
title: "test"
format: html
editor: visual
date: today
---

Similarly, you may change the output format under YAML parameter format. Quarto supports output formats like HTML, PDF, MS Word, ePub, Jupyter and many more (see all Quarto Formats).

Note

Alternatively, YAML-configurations may be specified on a project level (separate file named _quarto.yml) or on a code chunk level (see YAML Locations).

In Quarto, code blocks start and end with three backticks. To identify an R code block, use {r} right after the opening backticks. For example:

summary(cars)
     speed           dist       
 Min.   : 4.0   Min.   :  2.00  
 1st Qu.:12.0   1st Qu.: 26.00  
 Median :15.0   Median : 36.00  
 Mean   :15.4   Mean   : 42.98  
 3rd Qu.:19.0   3rd Qu.: 56.00  
 Max.   :25.0   Max.   :120.00

Other supported languages include Python, Julia, and Observable JS.

You can customize how code behaves in your document using execution options. For example, the chunk option #| echo: false hides the code from the output but still runs it. The option #| eval: false shows the code but does not execute it — useful for teaching, documentation, or drafts where you want to show syntax without generating output. A full list of execution options is available here.

Exercise

Insert the following code into your Quarto document, add some explanatory text below the chart of results and render as HTML:

library(ggplot2)
ggplot(data=cars, aes(x=speed, y=dist)) +
  geom_point() +
  geom_smooth()

This simple exercise illustrates the fundamental benefit of Quarto. It facilitates weaving together narrative text and code into data reports and documents that can be exported in various formats.

11.3.1 Under the Hood - the Render Pipeline

When you click Render, Quarto runs a processing pipeline behind the scenes that converts your .qmd file into the final document. This happens in three steps:

  1. knitr executes your code chunks and generates a Markdown (.md) file. This intermediate file combines your code, output, and written content into a single Markdown document.

  2. pandoc converts the Markdown into the final output format (HTML, PDF, Word, etc.).

  3. The finished output opens in the RStudio Viewer or browser.

.qmd  -->  knitr(r)/jupyter(py) (code runs) --> .md  -->  pandoc --> HTML | PDF | Word
                                            ▲                    ▲
                                    executes R/Python   LaTeX, styling, layout

You can specify the desired output format in the document’s YAML front matter or in the _quarto.yml config file.

Understanding this pipeline is helpful when debugging — you’ll know whether a problem comes from code execution, Markdown conversion, or final document rendering.

For more details, see the Quarto Documentation.

11.4 Synchronizing with GitHub

Regular synchronization of your local changes with the online repository is a key practice in version control. Start by pulling any updates from the repository.

In the RStudio Git tab, click the “Pull” button (see Figure 11.7). A notification should indicate whether any new changes are available (e.g., Already up to date).

Figure 11.7: Make Pull

Even if you’re working on your own, it’s a good idea to routinely start the sync process with a “Pull”.

Next, commit your changes. Think of committing as taking a snapshot of your progress, accompanied by a descriptive message.

First, save all documents in RStudio. Then, hit the “Commit” button in the Git tab. The commit window will display a list of modified files. Green highlights indicate new content; red highlights show deleted content. This is called a diff view, showing the exact changes made since your last commit.

Check the boxes next to each file you want to include, then enter a commit message describing the changes. Alternatively, run git add -A in the terminal to add all files at once (see this list of popular Git commands). After selecting files, enter a meaningful commit message and click “Commit”.

See Figure 11.8.

Figure 11.8: Make Commit

Finally, push your committed changes to the online repository:

Figure 11.9: Make Push

Your online repository on GitHub should now be updated (switch to dev branch in your repository) (see Figure 11.10).

Figure 11.10: Commit with message ‘test’ was pushed to the dev branch a minute ago

In our example, the dev branch is two commits ahead of the main branch. To share your updates or integrate them into the stable version, you can open a pull request to merge dev into main.

11.5 Basic Markdown Syntax

In Quarto, text formatting is based on Markdown — a lightweight markup language that uses plain text symbols to control layout.

Commonly used markers are…

Bold: Double asterisks **Text** turn text bold.

Italicize: Single asterisks *Text* create italicized text.

Headings: Use hash signs # for headings. The number of hashes denotes the heading level:

# Heading level 1

## Heading level 2

### Heading level 3

Tables are created by using the symbols | and -. For example, the numeric operators table in the first lesson was written in Markdown. Figure Figure 11.11 shows how such a table is constructed.

Figure 11.11: How Tables are made in Markdown

To create an ordered list, use numbers followed by a period. The first item should start with the number 1:

Code - Ordered List:
1. item 1
1. item 2
1. Item 3
    + Item 3a
    + Item 3b

Will result in:

  1. Item 1
  2. Item 2
  3. Item 3
    • Item 3a
    • Item 3b

To create an unordered list, use *, -, or +:

Code - Unordered List:
* item 1
* item 2
  * Item 3.1
  - Item 3.2

Which will result in:

  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Hyperlinks are created with the format [Text](URL), for example, [GitHub](https://github.com/){target="_blank"} becomes GitHub. The target="_blank" parameter opens the link in a new tab, which is a good practice when linking to external websites.

Blockquotes are indicated by > and can be nested:

>"Everything is related to everything else, but near things are more related than distant things".
>
>>The phenomenon external to an area of interest affects what goes on inside.

Will result in:

The first law of geography is: “Everything is related to everything else, but near things are more related than distant things”

The phenomenon external to an area of interest affects what goes on inside.

By now, you’ve seen that some characters (like #, *, > or $) have special meaning in Markdown. If you want to show them literally in your text, you need to escape them by adding a backslash (\) before the character.

For example:

\# shows a hash symbol #

\* shows an asterisk *

Quarto supports a large number of mathematical notations using dollar signs $:

Math. notation example 1:

$x = y$

Result looks like:

x = y

Math. notation example 2:

$\frac{\partial f}{\partial x}$

Result looks like:

\frac{\partial f}{\partial x}

Note

See “Mathematics in R Markdown” as well as Markdown Basics for more.

11.5.1 References in Quarto

Quarto makes it easy to insert citations and automatically generate a bibliography — using a .bib file to store reference metadata.

To begin, create a new plain-text file in a simple editor (e.g., Notepad, VS Code, or RStudio’s built-in editor), and save it with a .bib extension (e.g., references.bib) in your RStudio project folder.

  1. Enable BibTeX Export: Modify your settings in Google Scholar to enable BibTeX export (see Figure 11.12).
Figure 11.12: Enable BibTeX in Firefox 106.0.1

Browser versions may vary. For assistance, refer to the discussion forum if needed.

  1. Export BibTeX Entries: After enabling BibTeX export, a new link “Import into BibTeX” will appear in Google Scholar (see Figure 11.13).
Figure 11.13: BibTeX Link in Firefox 106.0.1

Click the link and copy the BibTeX code into your .bib file.

  1. Integrate References in the Quarto document: Specify the location of your .bib file in the YAML metadata of your Quarto document (bibliography: <.bib file>). Insert @ followed by the BibTeX key to add citations (see Figure 11.14).
Figure 11.14: Integrate BibTeX reference in Quarto document
  1. Compile the Document: Render the Quarto document as HTML. Quarto processes both indirect (without square brackets) and direct citations (with square brackets) and includes a bibliography (see Figure 11.15).
Figure 11.15: Quarto with reference

For a practical demonstration, download and explore this Quarto reference example. Unzip the folder and open the .Rproj file in RStudio.

11.6 Extending Quarto with Extensions and Filters

Quarto’s core is deliberately light, but you can extend it with optional community-built extensions especially useful for advanced customization or automation.

11.6.1 How it works under the hood

  1. quarto add … downloads the extension into an _extensions/ folder at your project root (commit this folder so collaborators get the same behaviour).
  2. During render, pandoc automatically loads any Lua filters it finds there.
  3. These filters modify the document on the fly—e.g. injecting diagrams or styling call-outs.

Why Lua? Pandoc’s native filter language is Lua, so Lua scripts run with zero external dependencies and maximum speed.

11.6.2 One-line install example

# Adds a custom-callout filter; the Exercise boxes in this module are created with it.
quarto add coatless-quarto/custom-callout

A catalog of community-maintained add-ons (plus a short “write your own” guide) lives in the Quarto Extension Gallery.

Filters need to be listed in your _quarto.yml:

filters:
  - webr
  - custom-callout

This tells Quarto to activate these filters during rendering.

(Always check the extension’s README for extra setup instructions.)

11.7 Speed up your workflows

Quarto significantly enhances the efficiency of repetitive workflows. For instance, consider a scenario where a client requires daily updates on specific spatial economic indicators. Instead of manually generating a new report each day, Quarto can automate this process, creating data reports with charts that update automatically upon compilation. This approach can save substantial time and effort.

Real-time data retrieval is possible through Alpha Vantage, which provides financial market data via the Alpha Vantage Rest API. The R library alphavantager facilitates API access within R. The use of alphavantager enables the extraction of various types of financial data, including real-time stock prices, FX rates, and technical indicators, directly into R. This allows for efficient data processing and visualization, making it a good tool for finance-related reports and analyses in Quarto.

Note

The free Alpha Vantage tier is limited to 25 API requests per day.

Exercise

Explore a practical example by downloading this draft finance data report. Unzip the folder and open the .Rproj file in RStudio.

The project includes:

  • A .bib file with a BibTeX reference.
  • A .csv file in the data folder, listing over 400 country names, national currencies, and currency codes.
  • A .qmd file with inline R code that renders real-time currency exchange rates in a map.

Review the .qmd file thoroughly before compiling an HTML output. Note that it includes an interactive Leaflet map, making HTML the only supported output format.

Try enhancing the report with an additional spatial indicator, such as a map displaying exchange rates from national currencies to the Euro.

11.8 Self-study

The vast functionalities of Quarto extend beyond the scope of a single lesson. To fully exploit its capabilities, refer to the comprehensive Quarto Guide.

This guide covers additional topics such as the integration of figures or cross references, computations in various languages such as R, Julia, and Observable and formats such as quarto projects, presentations, dashboards, websites, books or manuscripts.

Note

To find inspiration for your own projects you may consult the Quarto Gallery that provides a variety of Quarto best practice examples.