Intro to Quarto

To Tell Your Story with Data

Welcome

• Welcome

• Introduction to Quarto

• Getting Started

About me

ivelasq

ivelasq

ivelasq.rbind.io

ivelasq3

About you

Please share in the chat…

• Your name
• Your professional affiliation
• What you produce with data (reports, dashboards, etc.)
• What programming language you use

About this workshop

These materials are pitched at someone who:

• knows some R or Python
• has R or Python installed
• creates documents that display output from code
• new to Markdown and Quarto

What you will walk away with:

• An introductory knowledge of Quarto and its benefits of telling stories with data
• Examples of documents with code

Workshop structure

My turn

• Lecture segments
• Feel free to just watch, take notes, browse docs, or tinker around with the code

Our turn

• Lecture segments + live coding
• (Optionally) Follow along with live coding

Your turn

• Practice exercises for you!
• Ask questions in the chat if you run into issues

Instructions

• Workshop website: bit.ly/gasp2025-quarto
• Workshop exercise repo: https://github.com/ivelasq/gasp2025-quarto-exercises

Introduction to Quarto

• Welcome

• Introduction to Quarto

• Getting Started

What is Quarto®?

Quarto® is an

open-source

scientific and technical

publishing system

built on Pandoc.

Quarto is an open-source scientific and technical publishing system built on Pandoc. Let’s break this down: Open-source: Posit believes that it’s better for everyone if the tools used for research and science are free and open. Free software means more reproducibility, widespread sharing of knowledge and techniques, and elimination of cost barriers. Scientific and technical: Scientific and technical means that Quarto has specific things for journal articles or scientific papers, like support for code execution, citations, footnotes, scientific markdown, equations, citations, crossrefs, so many things. Publishing system: Quarto is a tool for writing dynamic documents that combine code, output, and text. It can embed output from Python, R, Julia, and Observable. Quarto can be rendered to create high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more formats. Pandoc is the tool working behind the scenes to change Quarto documents to their finalized format. Quarto documents are authored with markdown, which is a plain text format. But Pandoc markdown is very rich and lets you control your document in very specific ways while being easy to read and write.

With Quarto…

you can weave together narrative and code to produce elegantly formatted output as documents, web pages, blog posts, books and more.

• Create dynamic content with Python, R, Julia, and Observable
• Edit documents in your favorite editor
• Publish technical content in HTML, PDF, MS Word, and more
• Share technical content by publishing to Posit Connect, Confluence, or other publishing systems

“Literate programming”

Quarto sits inside the big and broad literate programming world, which mixes narrative in text form with code for formatted outputs like documents and webpages and more. There are lots of literate programming systems that support computation, like R Markdown, Org Mode, Jupyter Book, and now there is Quarto!

Why Quarto?

• Multilingual and independent of computational systems
• Quarto comes “batteries included” straight out of the box
• Consistent expression for core features
• Extension system
• Enable “single-source publishing” — create Word, PDFs, HTML, etc. from one source
• Use defaults that meet accessibility guidelines

So, if there already exist literate programming tools out there, why create a new one? Like mentioned earlier, Quarto was built from the start to support multiple computational systems and ecosystems. You can create presentations, books, websites, and so on after installing Quarto, you do not have to install other tools to create different things. Consistent expression for core features means that regardless of whether you are making a presentation, book, or website, the syntax is written same way. And for things that aren’t part of base Quarto, there are extensions that can add further functionality. Single-source publishing, you often need to create all sorts of output, like things that are printed, on the web, on the mobile. The idea is to being able to make publications from one source. And the Quarto team thinks deeply about accessibility and how to have Quarto default to meet accessibility guidelines.

Why Quarto for telling stories with data?

A good story is…

• Clear
• Credible
• Provides context
• Engaging

Quarto allows you to…

• Use many formats for telling your story
• Reproduce and automate results
• Add footnotes, cross-references
• Mix code and narrative together

Quarto formats

Feature	Quarto
Basic Formats	html, pdf, docx, typst
Beamer	beamer
PowerPoint	pptx
HTML Slides	revealjs
Advanced Layout	Quarto Article Layout
Cross References	Quarto Crossrefs
Websites & Blogs	Quarto Websites, Quarto Blogs
Books	Quarto Books
Interactivity	Quarto Interactive Documents
Journal Articles	Journal Articles
Dashboards	Quarto Dashboards

Quarto capabilities

Built for technical documents:

Cross references
Advanced layout
Figure/layout panels
Callouts
Diagrams
Extensions
Interactivity
YAML intelligence
Publishing
Conditional content
Notebook filters

Features are constantly being build into Quarto, like YAML intelligence, figure panels, layouts, which we’ll cover later in the session.

Display data and results

Vote Idaho Election Page by Andrew Heiss (Department of Public Management and Policy, Georgia State University) and the Idaho Secretary of State

Let’s see some examples of how people have used Quarto to tell their stories. Andrew Heiss, in conjunction with the Idaho Secretary of State’s office, created a Quarto website for Idaho’s primary election results.

Display data and results

Health Trends in England by the Department of Health & Social Care

The Department of Health & Social Care in England created a Health Trends tool to open up public health data to a broader audience, and were shortlisted in the Analysis in Government award.

Walk through a story

Council Housing & Neighborhood Income Inequality in Vienna by Tamara Premrov and Matthias Schnetzer (European Centre for Social Welfare Policy and Research, Austria)

Posit recently held a Scrollytelling contest. You may have seen articles in newspapers like the New York Times that display visualizations as you scroll through the document. Quarto has an extension called Scrollytelling that lets you create these sorts of stories in Quarto. This one, from folks at the European Centre for Social Welfare Policy and Research which talked about Housing & Neighborhood Income Inequality in Vienna, was one of the winners.

Publish papers

Navigating Hostility: The Effect of Nonprofit Transparency and Accountability on Donor Preferences in the Face of Shrinking Civic Space by Suparna Chaudhry (Lewis & Clark College, International Justice Lab at College of William & Mary) et al.

Quarto also has extensive features for writing journal articles, from diagrams and technical notation, to being able to publish according to journal standards through extensions.

Automate and reproduce your output

Duplicating Quarto elements with code templates to reduce copy and paste errors by Althea A. Archer (United States Geological Survey)

With Quarto, you can create reports or presentations that update automatically when data changes or when you change inputs because you are creating your report with code. There’s a software engineering concept called the DRY Principle (“Don’t Repeat Yourself”) that is useful in data work that encourages writing code that can be reused with functions or loops instead of copy/paste. Use variables (parameters) to dynamically change parts of your analysis or report like to generate the same report for different regions, departments, or time periods, write reusable functions to avoid repeating code and keeps work cleaner, more consistent, and easier to maintain. The folks at United States Geological Survey have great blog posts on how they are implementing these ideas in Quarto.

Get your team on the same page

We Converted Our Documentation to Quarto by Melissa Van Bussel (Statistics Canada)

• Website for R/Python User Group
• Training resources
• Presentations

And finally, Melissa van Bussel gave a talk on how the Statistics Canada team converted not just their documentation, but training resources, presentations, and more to Quarto to streamline efforts.

️Wrap Up

Quarto + Communication = ❤

Photo by Kelly Sikkema on Unsplash

Getting Started

• Welcome

• Introduction to Quarto

• Getting Started

Installation

You can download the Quarto Command Line Interface, or CLI, on quarto.org. When you download the Quarto CLI, though, that’s all you need to run Quarto, so you can use just your Terminal or Command Line Interface for everything that we’ll explore, but you will need to install a programming language if you’re going to run code with the CLI.

quarto.org/docs/get-started/

Tools for authoring

Terminal

quarto render

Part of the multilingualism of Quarto is that you are not tied to one tool. Quarto is meant for collaboration either within data science teams or across data science teams. So if someone is familiar with VS Code, but someone else likes to work in RStudio, they can still work on the same Quarto documents without having to switch to one tool or the other.

Our turn

Let’s walk through your options for today.

1. Posit Cloud
2. GitHub Codespace
3. Local installation

• GitHub repository
• Package installation

Posit Cloud has R, RStudio, Quarto, packages, installed. You just need a free account. But I will delete in a few days. If you prefer Python, there is a GitHub Codespace. It takes many minutes to load so please open it up as soon as you can if you’d like to go this route. The packages will not come preinstalled, but the instructions are on the website. Finally, you can always install Positron, RStudio, or VS Code locally, but you will also need R or Python installed. You’ll also have to install the packages and download the repo materials. So, if you do not have these set up, I recommend going with Posit Cloud or GitHub Codespace for now, and coming back to the materials after the workshop.

Your turn

Go to the workshop website and click on 00 - Introduction in the sidebar.

bit.ly/gasp2025-quarto

Follow the setup instructions at the bottom.

05:00

Our turn: Quarto workflow

• Open a .qmd file.
• Preview/render the document.
• Make a change and preview/render again.

Your turn

• Open the 01-exercise-py.qmd or 01-exercise-r.qmd file.
• Preview/render the document.
• Edit the title and preview/render again.

05:00