Creating documents with Quarto

Quarto lets you create professional reports and papers directly from RStudio, combining code, text, and visualizations in a single reproducible workflow. This tutorial covers the basics of working with Quarto files in RStudio, then walks through creating report-style documents specifically. The next tutorial covers presentations.

Working with Quarto in RStudio

To start a new Quarto document in RStudio:

  1. Go to File → New File → Quarto Document…
  2. Enter a title, author, and choose a default output format (e.g., HTML, PDF, or Word).
  3. RStudio creates a .qmd file containing a template YAML header and an example code chunk.
  4. Click Render (or use Render on Save) to produce the formatted output.

RStudio Quarto new document dialog (source: https://quarto.org)
Reading

For more information, see the official Quarto documentation: Authoring with RStudio

Every .qmd file has the same basic structure: a YAML header (between --- lines) defining metadata like title and output format, a body written in Markdown, and optional embedded R code chunks.

YAML: Document Metadata and Configuration

The YAML header is where you tell Quarto how to render your document: what format to produce and which options to apply. It uses a simple key-value structure, enclosed between --- at the start and end of the block.

---
title: "Statistical Analysis of Air Quality Data"
author: "Alex Rivera"
date: "2025-01-01"
format:
  html:
    toc: true
    code-fold: true
---

Do: Create a Quarto document on your own computer. In the YAML header of the .qmd file, change format: html to format: pdf in the header. Do you expect this to be a one-line switch, or would you need to change other parts of the document too?

See: For a simple document, changing the target format really can be that simple: the same Markdown body and code chunks are reused. In practice, though, some format-specific options (like code-fold, which is an HTML-only feature) won’t carry over, and PDF output has its own setup requirements, covered below.

Creating Reports and Papers

Common document output formats include:

Format Output Type Typical Use
html Interactive web report Exploratory data reports, dashboards
pdf Print-quality report Academic papers, formatted submissions
docx Microsoft Word Editable reports for collaboration
epub e-book Long-form reading materials

Quarto automatically executes embedded code chunks and inserts the resulting tables and plots, so every time you re-render, the analysis and visuals update from your current data.

A few things to keep in mind across formats:

  • Layout: reports may need page breaks or fixed figure sizing, especially for PDF and Word.
  • PDF rendering requires a working LaTeX installation (e.g., TinyTeX).
  • Settings don’t always transfer: an option that works for HTML may not apply to PDF or Word.
  • Citations are supported via BibTeX, covered later in this module.
Common Mistake

By default, a rendered HTML report can reference supporting files, such as separately saved images, rather than embedding everything into the single .html file. If you then hand in or share only that .html file, without its supporting files, it can open broken or missing content for whoever receives it. To avoid this, set your document to be self-contained by adding embed-resources: true under your HTML format options:

format:
  html:
    embed-resources: true

This produces a single, fully portable .html file with everything, including plots and images, embedded inside it. This is important whenever you’re submitting a report as one file, for example for a homework assignment.

Reading

Learn more: Quarto Document Formats

Practice Exercise

Write a YAML header for an HTML report titled “Analysis Report,” with a table of contents, that is safe to hand in as a single file.

---
title: "Analysis Report"
format:
  html:
    toc: true
    embed-resources: true
---

The toc: true option adds a table of contents, and embed-resources: true ensures the rendered .html file is self-contained, so it can be shared or submitted on its own.

Back to top