Creating Documents with Quarto

March 11, 2026 · 5 min read · Updated March 11, 2026 · beginner

quarto markdown documents publishing rmarkdown

Quarto is an open-source scientific and technical publishing system built on Pandoc. It extends R Markdown to support reproducible research workflows in Python, R, Julia, and Observable. This guide shows you how to create documents with Quarto.

Why Quarto?

Quarto solves several limitations of R Markdown. It provides a unified authoring framework across programming languages. The output quality is higher by default. YAML configuration is cleaner and more consistent. Projects can mix multiple languages in a single document.

If you already know R Markdown, Quarto feels familiar but with improved syntax and capabilities. The main benefits include consistent syntax across languages, better defaults for figures and tables, native support for Jupyter notebooks, and improved extension system.

Installing Quarto

Install Quarto from the command line or download from the official website:

# macOS
brew install quarto

# Linux
sudo wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.550/quarto-1.4.550-linux-amd64.deb
sudo dpkg -i quarto-1.4.550-linux-amd64.deb

# Windows
choco install quarto

In R, verify the installation:

quarto::quarto_version()

Creating Your First Quarto Document

A Quarto document is a plain text file with the .qmd extension. The header contains YAML metadata between --- delimiters. Below the header, you write markdown content mixed with code blocks.

---
title: "My First Quarto Document"
author: "Your Name"
date: "2026-03-11"
format: html
---

Add R code using a code chunk:

# This is an R code chunk
summary(cars)

The triple backticks with r tell Quarto to execute the code with the R engine. Output appears below the code block in the rendered document.

Rendering Documents

Render your document from the R console:

quarto::quarto_render("document.qmd")

Or from the terminal:

quarto render document.qmd

Quarto produces output in the _quarto directory by default. The output filename matches the input with the appropriate extension.

Output Formats

Quarto supports multiple output formats. Change the format option in the YAML header:

HTML Documents

format: html

HTML is the default format. Add options for styling:

format:
  html:
    toc: true
    number-sections: true
    theme: cosmo
    css: styles.css

The toc option generates a table of contents. number-sections adds section numbers automatically. Themes include cosmo, bootstrap, sandstone, and many others.

PDF Documents

format: pdf

PDF output requires a LaTeX installation. The tinytex package provides the easiest setup:

install.packages("tinytex")
tinytex::install_tinytex()

After installation, rendering to PDF works automatically:

quarto render document.qmd --to pdf

Word Documents

format: docx

Word output is useful for collaborative workflows where colleagues prefer Microsoft Word. The output is a .docx file that can be edited in Word or Google Docs.

Code Execution Options

Control how code chunks execute with options in the YAML header or inline. These options give you fine-grained control over what readers see.

execute:
  echo: true       # Show source code
  warning: false   # Hide R warnings
  error: true      # Show error messages
  include: false   # Hide code, show output only

Set options per-chunk using the hash-pipe syntax:

#| echo: false
#| warning: true
#| fig-width: 6
#| fig-height: 4
summary(cars)

The hash-pipe syntax is the recommended approach for Quarto documents. It keeps options close to the code they affect.

Figures and Tables

Quarto automatically numbers figures and tables. Reference them in your text using the @ symbol. This creates clickable links that jump to the figure or table.

For figures, add a label and caption in your code chunk:

#| label: fig-scatter
#| fig-cap: "Scatter plot of pressure"
plot(pressure)

Reference it in your text as @fig-scatter. Quarto generates the figure number automatically based on its position in the document.

Tables work similarly with the tbl-cap option:

#| label: tbl-summary
#| tbl-cap: "Summary statistics"
#| echo: false
kable(summary(cars))

The kable() function from the knitr package produces nicely formatted tables.

Cross-References

Add cross-references to sections, equations, and code blocks. Label sections directly in their headings:

## Introduction {#sec-intro}

See @sec-intro for the background.

The curly brace syntax assigns a label to the section. Reference it with the @ symbol elsewhere in the document.

For equations, wrap in dollar signs for inline or double dollar signs for display math:

The mean is calculated as:

$$\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i$$

Parameterized Reports

Create reports that generate different outputs from the same template. Parameters pass values into the document at render time.

---
title: "Sales Report"
format: html
params:
  region: "US"
  year: 2025
  product: null
---

Access parameters in R code:

library(dplyr)

sales_filtered <- sales |>
  filter(region == params$region, year == params$year)

if (!is.null(params$product)) {
  sales_filtered <- sales_filtered |>
    filter(product == params$product)
}

Render specific parameter values from R:

quarto::quarto_render("report.qmd",
  params = list(region = "EU", year = 2025))

Parameterized reports are useful for recurring reports like monthly sales summaries or quarterly analytics.

Projects

Quarto projects organize multiple documents into a website, book, or blog. Create a project directory with a configuration file:

project:
  type: website
  output-dir: _site

website:
  title: "My Documentation"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: guide.qmd
        text: Guide

Build all documents in the project:

quarto render myproject/

Projects handle navigation, cross-references across files, and shared resources automatically.

Publishing

Quarto includes publishing commands for various platforms. Each platform has specific requirements.

GitHub Pages

quarto publish gh-pages

This command builds the project and pushes to the gh-pages branch.

Netlify

quarto publish netlify

Netlify provides continuous deployment from your repository.

Posit Connect

quarto publish connect

Posit Connect hosts Quarto documents with enterprise authentication and scheduling.