Starting with Quarto 1.9, quarto install chromium is deprecated. The recommended replacement is Chrome Headless Shell , a lightweight, headless-only browser from Google’s Chrome for Testing infrastructure.

Why the switch?

Puppeteer-bundled Chromium served Quarto well, but it had limitations that kept coming up:

• System dependencies in containers: The Puppeteer Chromium binary requires system libraries that aren’t always present in minimal Docker images or WSL environments. This led to cryptic errors that were hard to debug.
• No arm64 Linux support: Puppeteer didn’t distribute Chromium builds for arm64 Linux, leaving users without an easy install path.
• Large download size: The full Chromium bundle is significantly larger than what Quarto actually needs for headless rendering.

Chrome Headless Shell solves all three. It’s purpose-built for headless automation, has fewer system dependencies, ships arm64 Linux builds, and is smaller to download.

Installing Chrome Headless Shell

If you don’t already have Chrome or Edge installed on your system, install Chrome Headless Shell:

1

quarto install chrome-headless-shell

Quarto will automatically detect and use any existing Chrome or Edge browser on your system. Chrome Headless Shell is the recommended fallback for environments where a full browser isn’t available — CI servers, Docker containers, and headless VMs.

Migrating from Chromium

If you previously installed Chromium via quarto install chromium, the migration is straightforward:

1
2

quarto uninstall chromium
quarto install chrome-headless-shell

Running quarto check install will warn you if a legacy Chromium installation is detected and suggest the migration.

CI and automation

If your CI pipeline uses quarto install chromium --no-prompt, it will continue to work — the command still installs a working headless browser, but now shows a deprecation warning. Updating your scripts to quarto install chrome-headless-shell --no-prompt avoids the warning and uses the new tool directly. In Quarto 1.10, quarto install chromium will transparently redirect to Chrome Headless Shell, so either command will produce the same result.

What’s next

The transition away from Puppeteer Chromium is happening gradually. In Quarto 1.9, quarto install chromium shows a deprecation warning and quarto check install flags any legacy Chromium installation. In the upcoming Quarto 1.10, quarto install chromium will transparently redirect to Chrome Headless Shell, and installing Chrome Headless Shell will auto-remove any legacy Chromium.

If you’re still using the old Chromium install, now is a good time to switch.

Learn more on the Chrome Install documentation page.

The Chromium icon in the listing and social card image for this post is by Jeremiah via icon-icons.com. License: CC BY 4.0

Yet preparing replication materials can be daunting, especially for researchers new to data science. It is not uncommon for scholars to struggle to reproduce even their own results, due to issues such as disorganized code and data, software version mismatches, missing random seeds, or differences in operating systems and platforms. While some of these challenges are complex, many reproducibility problems stem from preventable organizational issues. Structuring code and data in a clear, consistent, and tool-friendly manner can significantly reduce these difficulties — and brings additional benefits at virtually no cost, including smoother collaboration and easier integration with AI tools.

In this post, I’ll walk through the project structure I use in my own research. It has evolved over time and reflects what I currently consider best practice for reproducible academic work. Adopting a clear structure from the outset makes it significantly easier to reproduce results, onboard collaborators, and maintain projects over the long term.

The structure covers the full research lifecycle: from data cleaning and analysis to manuscript preparation and presentation. The template is built around R and Quarto (the successor to R Markdown), but the underlying principles translate easily to Python and other publishing workflows, including LaTeX. For convenience, I’ve created a ready-to-use template on GitHub that you can clone and adapt for your own projects.

The project structure looks like this:

I’ll now break down each component in turn, explaining the purpose of the key folders and files, and the reasoning behind the design.

Git and GitHub

One major threat to reproducibility is a file named latest_final_v3_definitive.R. While this naming convention feels natural during exploratory analysis—especially under deadline pressure—it quickly becomes impossible to reconstruct what actually changed, when, and why. Future-you (and your collaborators) will not be grateful.

Version control systems like Git solve this problem by recording a structured history of changes through commits. Instead of creating new files for every iteration, you preserve a single evolving project with a transparent timeline. This makes it easy to revisit earlier versions, understand how results evolved, and collaborate without overwriting each other’s work.

GitHub builds on this by providing a shared platform for hosting repositories, reviewing changes, managing issues, and coordinating collaboration. It also makes it very clear who introduced a particular change—an accountability feature that tends to concentrate the mind when committing code.

In the example project structure, several files and folders are Git-related:

.git/ (invisible folder created by Git)
.gitignore
*.gitattributes
*/
└── .gitignore

The .git/ folder is created automatically when you initialize a repository. It contains the full version history and metadata of the project. You generally do not need to interact with it directly—just avoid modifying or deleting it.

The .gitignore file specifies which files and folders should be tracked or ignored by Git. Since all changes to tracked files are recorded in the project history, a useful rule of thumb is to track only what is necessary to reproduce your results. Files that can be regenerated from code—such as intermediate data, plots, tables, or compiled PDFs—are often better ignored to keep the repository clean and lightweight.

The .gitattributes file defines additional rules for how Git should handle specific file types. Compared with .gitignore, it appears less often in many repositories, but it is especially useful when you need file-type-specific behavior. In particular, large raw data files (e.g., large .csv files) and binary formats (such as .rds, .RData, or images) can significantly increase repository size if tracked directly. In these cases, Git Large File Storage (Git LFS) can be used to store the actual files separately, while keeping lightweight pointer files in the main repository history.

Data directories

I use two separate folders to store raw (data_raw/) and cleaned data (data_processed/). Keeping these distinct makes the workflow more transparent: the original data remains untouched, while processed data can be saved in a format that is fast to load during analysis.

This structure also aligns with common journal expectations that replication code should be able to reproduce results starting from the raw data. By preserving raw inputs and separating preprocessing steps, you make the transformation pipeline explicit rather than implicit.

data_raw/
└── *.csv (tracked through Git LFS)

data_processed/
├── *.rds (not tracked in Git)
└── .gitignore

In the template, the example raw data file (data_raw/Brexit.csv) is tracked using Git LFS. While the file itself is neither large nor binary (unlike formats such as .dta or .rds), LFS is used here for demonstration purposes. In real-world research projects, raw datasets are often substantial in size, and setting up LFS early helps avoid repository bloat later on.

The data_processed/ folder contains the cleaned dataset in .rds format, along with a .gitignore file that excludes all files in this folder (except the .gitignore file itself) from version control. This design encourages regeneration of cleaned data from raw inputs via code, rather than relying on previously saved intermediate objects. It also helps keep the repository lightweight.

The .rds format is used for several reasons. First, it is a native R format that preserves data types and attributes faithfully. Second, it encourages the use of RDS over .RData. Unlike .RData, which loads all stored objects into the global environment under their original names, .rds files require explicit assignment when loaded. This reduces the risk of unintentionally overwriting existing objects and promotes more transparent workflows.

Finally, the .gitignore file inside data_processed/ serves an additional purpose: it ensures that the folder itself is tracked by Git. Since Git does not record empty directories, this placeholder guarantees that the directory exists when the project is cloned. This is important because saving cleaned data to a non-existent directory will otherwise result in an error in R.

For researchers working with confidential or restricted data, it is often helpful to separate sensitive materials from those that can be shared publicly. In some cases, this may mean maintaining a private repository during the research phase and preparing a separate public-facing repository upon publication.

Importantly, simply deleting confidential files before making a repository public is not sufficient. Git preserves the full commit history, meaning sensitive data may still be accessible in earlier revisions. Creating a fresh repository that contains only the materials intended for public release—such as replication code and non-sensitive data—helps prevent unintended data leakage.

This approach also makes it easier to curate a clean, well-documented version of the project specifically designed for replication and reuse.

Code organization and outputs

code/
├── 1_data_cleaning.R
├── 2_descriptive.R
└── 3_main_analysis.R

outputs/
├── *.rds (not tracked in Git)
└── .gitignore

The code/ folder contains all scripts related to data processing and analysis. In the template, these are written in R, but the same structure works equally well for Python scripts (.py), notebooks (.ipynb), or other programming languages.

A key principle is to prefix scripts with numbers and descriptive names that reflect the research workflow: data cleaning, descriptive analysis, and then inferential analysis. If the logical order of steps is unclear, following the sequence in which results appear in the manuscript is often a reliable guide. This makes the analytical pipeline explicit and allows others (and future-you) to reproduce results step-by-step.

Each script should include a header section with basic metadata about its role in the project. This may include the paper title, authors, purpose of the script, input files, and output files. Making inputs and outputs explicit helps clarify dependencies and encourages scripts that transform data rather than rely on objects lingering in the global environment.

Below is an example of an analysis script (code/3_main_analysis.R) I used in the template that follows these principles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

######## INFO ########

# PROJECT
## Paper: YOUR PAPER TITLE
## Authors: YOUR NAME

# R Script
## Purpose: This script performs linear regression analysis.
## Inputs: data_processed/Brexit.rds
## Outputs: outputs/regression_table.rds

# Setup ----

library(tidyverse)
library(here)
library(modelsummary)

i_am("code/3_main_analysis.R") # helps with relative paths

# Read in the cleaned data ----

brexit_data <- read_rds(here("data_processed/Brexit.rds"))

# Main analysis ----

model <- lm(leave ~ turnout + income + noqual, data = brexit_data)

# Output the model summary ----

reg_table <- modelsummary(model, stars = TRUE, output = "latex")
write_rds(reg_table, here("outputs/regression_table.rds"))

Two additional tips are worth noting. First, the # SECTION ---- syntax creates collapsible sections and structured outlines in RStudio and the Positron IDE. This makes longer scripts significantly easier to navigate and encourages more intentional organization of code.

Second, managing working directories is a seemingly basic task that is frequently mishandled—especially in collaborative projects. In RStudio, the recommended approach is to work within an .Rproj file, which defines a project root and ensures that relative paths behave consistently across machines. However, in many academic settings (including political science), this practice is not systematically taught. As a result, it is still common to see replication files from top journals that begin with something like setwd("~/Path/To/Project"), often commented out with the expectation that collaborators will manually adjust it.

This approach is fragile. It assumes a specific directory structure on every machine and introduces hidden dependencies on local file paths. Code that depends on setwd() is difficult to port, share, or automate.

Positron improves this situation by automatically setting the working directory to the folder opened in the IDE, encouraging a project-level workflow by default. However, many users carry over the habit of opening individual scripts rather than entire project directories.

The here package provides a robust solution that avoids reliance on the working directory altogether. By anchoring a script to the project root using here::i_am() and constructing paths with here(), file references become explicit and portable. This ensures that scripts run consistently across machines, IDEs, and collaboration environments—regardless of local directory structures.

The outputs/ folder complements this approach by providing a dedicated location for all results generated by the code. This includes intermediate objects (e.g., fitted models) and final products (e.g., tables and figures). If intermediate artifacts become numerous, they can be stored in a separate objects/ folder. The accompanying .gitignore file ensures that these generated files are not versioned, reinforcing the principle that results should be regenerated from code rather than preserved as static artifacts.

Virtual environments and dependencies (renv)

Many R users do not update their R or package versions regularly. In practice, the version in use is often determined by when the researcher first learned R—or when the machine was purchased, whichever is later. Deprecation warnings are politely ignored as long as the code continues to run.

The problem only becomes visible when code that worked perfectly on your old machine suddenly fails on a new machine—or worse, on a collaborator’s machine. At that point, dependency management stops being an abstract concern and becomes a very practical one.

A common solution to this problem is the use of virtual environments, which capture the exact package versions used in a project—a concept long established in the Python ecosystem. In R, the renv package provides a convenient way to create and manage project-specific libraries. Package versions remain fixed within the project, independent of updates to the global R installation or differences across collaborators’ machines.

The state of the environment is recorded in the renv.lock file, which is committed to Git. This file serves as a snapshot of the project’s dependency graph at a given point in time, including package versions and their sources. As a result, the same software environment can be reproduced on any machine with a simple call to renv::restore().

Three key components related to renv appear in the template structure:

renv/
.Rprofile
renv.lock

The renv/ folder contains the project-specific package library. Most of its contents are not tracked in Git, since the environment can be regenerated from the information stored in renv.lock. Additionally, some packages include compiled C or C++ code that is platform-specific, meaning those installed binaries are not portable across operating systems.

The .Rprofile file includes a line that automatically activates the renv environment when the project is loaded, ensuring that the correct package versions are used without manual setup.

Automatic activation, however, only works when the project is opened as a whole—for example, by opening the .Rproj file or the project folder in Positron. If individual scripts are opened in isolation, the working directory will not be set to the project root at startup, and the project-level .Rprofile will not be executed. This is yet another reason to adopt a project-level workflow rather than treating scripts as standalone files.

Quarto: manuscripts and presentations

The most visible stage of the research lifecycle is the dissemination of results—through manuscripts, presentations, and other public outputs. For quantitatively oriented researchers (which, if you have read this far, likely includes you), producing well-formatted documents that do justice to your carefully constructed tables and figures is essential.

Quarto is an open-source scientific and technical publishing system built on Pandoc. I use it for all of my manuscript writing and presentation slides, and I recommend it for researchers working in R, Python, or Julia. The template presented here is deliberately centered around Quarto, and in what follows I will briefly explain the reasoning behind that choice.

Why Quarto?

What makes Quarto stand out is its ability to run R, Python, or Julia code directly within a document, seamlessly integrating analysis and writing. Tables, figures, and results can therefore be generated and updated automatically as the underlying code changes, ensuring that the manuscript always reflects the current state of the analysis.

Quarto is not a replacement for output formats such as HTML, Microsoft Word, LaTeX, or Typst. Rather, it acts as a unifying layer that can render the same .qmd source file into multiple formats simultaneously. This flexibility allows format decisions to be postponed and adapted to collaborators, institutions, or journal requirements.

Beyond manuscripts, Quarto also supports presentation formats and full websites. Learning a single tool therefore enables the production of academic papers, conference slides, and project or personal websites within a consistent workflow.

While these capabilities may sound familiar to experienced R Markdown users, I would still argue that Quarto is worth trying—even for those already comfortable with R Markdown—for four main reasons:

1. Language-agnostic support: Quarto is designed to work seamlessly with multiple programming languages (R, Python, Julia). A document can be executed using the native engine for each language—for example, a Python-only document runs through a Jupyter kernel without requiring R¹, which is more friendly to non-R users.

2. Native support for extended features: Quarto includes built-in support for cross-referencing, citations, and advanced formatting without requiring additional packages or complex configurations. In contrast, R Markdown often relies on extensions such as bookdown to achieve similar functionality, which introduces additional dependencies. In practice, many students are taught only the basic R Markdown setup and may not be aware of these extensions. Quarto provides these features out of the box.

3. More scannable code cell/chunk options and syntax: R Markdown users may be familiar with setting document-wide execution options inside a setup chunk using knitr::opts_chunk$set(...), and specifying chunk options inline in a comma-separated format. While functional, this approach can become difficult to scan and maintain in larger documents.

   1 2 3 4 5 6 7

   ```{r} knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE, error = FALSE) ``` ```{r barplot, fig.cap='Bar plot for y by x.', fig.height=3, fig.width=5} # code for the bar plot ```

   In Quarto, document-level execution options are defined declaratively in YAML, while cell-level options use a multi-line, command-style syntax. This makes both levels of configuration easier to scan, and typically easier to review in diffs and modify.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   ```yaml execute: echo: false warning: false error: false message: false ``` ```{r} #| label: fig-barplot #| fig-cap: 'Bar plot for y by x.' #| fig-height: 3 #| fig-width: 5 # code for the bar plot ```

4. Centralized documentation: While R Markdown benefits from a large community and extensive online resources, its documentation is distributed across multiple sites². Quarto, by contrast, maintains a single, comprehensive documentation portal that covers core usage and advanced features in one place, making it easier to navigate and learn systematically.

Quarto project structure

The remaining components of the template are primarily related to Quarto. Below, I break down the key elements and explain the reasoning behind their organization.

_extensions
.quarto (created by Quarto; not tracked in Git)
extras/
manuscript/
├── manuscript.pdf (not tracked in Git)
└── manuscript.qmd
slides/
├── slides.pdf (not tracked in Git)
└── slides.qmd
_quarto.yml

Configuration file

The _quarto.yml file serves two main purposes.

First, it defines project-level execution behavior. In particular, the following setting ensures that code is executed relative to the project root, regardless of where individual .qmd files are located:

1
2

project:
  execute-dir: project

This provides an additional layer of protection for resolving relative paths correctly. Used together with the here package, it helps ensure that file paths behave consistently across different machines and execution contexts.

Second, _quarto.yml centralizes shared configuration options so they do not need to be repeated in each individual .qmd file. This reduces duplication, minimizes the risk of inconsistencies, and improves readability across documents.

In the template, shared options include the bibliography file and citation style:

1
2

bibliography: extras/references.bib
csl: extras/apa.csl

Because these settings are defined at the project level, they apply automatically to both the manuscript and presentation slides.

Extras: bibliography and citation styles

As mentioned above, the extras/ folder contains the bibliography file (references.bib) and citation style file (apa.csl). These are referenced in the _quarto.yml configuration file, which means they are automatically available to all .qmd files in the project without needing to specify them individually.

extras/
├── references.bib
└── apa.csl

Ideally, if you have other supplementary materials that are not part of the core code or data but are still relevant to the project (e.g., codebooks), they could also be stored in this folder. However, I have kept it focused on bibliography-related files for simplicity.

Bibliography file

The references.bib file is a standard BibTeX/BibLaTeX bibliography file familiar to LaTeX users. It contains structured reference entries, including fields such as author, title, journal, year, and other publication metadata.

Entries can be exported from reference managers such as Zotero or Mendeley, or generated directly within Quarto using the Visual Editor. Crucially, the bibliography file is kept separate from both the manuscript and the citation style. This separation allows the same reference database to be shared across manuscripts and slides, while making it easy to change formatting styles without modifying the source content.

Citation style file

The apa.csl file is a Citation Style Language (CSL) file that defines how citations and bibliography entries are formatted. It acts as a translation layer between the structured data in references.bib and the rendered output format.

In this template, the CSL file specifies APA style, which is common in the social sciences. However, switching styles is straightforward: replace the apa.csl file with another CSL file (e.g., Chicago, MLA, or a journal-specific style) and update the reference in _quarto.yml. No changes to the manuscript text are required.

To find a CSL file for a specific discipline or journal, you can browse the CSL Style Repository , which contains thousands of maintained styles.

Manuscript

Dissemination of research findings is the ultimate goal of the research process, and the manuscript remains its primary vehicle.

manuscript/
├── manuscript.pdf (not tracked in Git)
└── manuscript.qmd
_extensions/
└── kv9898/
    └── orcid/

The manuscript/ folder contains the Quarto source file (manuscript.qmd) and the compiled PDF output (manuscript.pdf). As with other generated artifacts, the PDF is excluded from version control because it can always be regenerated from the source document.

The example manuscript.qmd provides a minimal template illustrating a typical academic structure, including numbered sections, figures, tables, cross-references, and citations. The template is intentionally simple but can be extended with additional formatting and structural elements as needed.

While Quarto’s built-in PDF format supports core elements such as title, authors, date, and abstract, more specialized academic requirements—such as detailed affiliation formatting, ORCID display, keywords, custom headers, or journal-style front matter—often require additional customization.

To address this, I created a custom extension that builds on the default PDF format and adds features commonly required in academic manuscripts. The extension is included in the template under _extensions/kv9898/orcid/.

Packaging the manuscript format as a Quarto extension ensures that formatting logic is versioned and shared alongside the project, rather than maintained as ad hoc local tweaks. The extension is activated via the YAML front matter of manuscript.qmd:

1
2

format:
  orcid-pdf:

The resulting PDF output more closely resembles a conventional academic paper, with structured author information, affiliations, ORCID identifiers, and keywords clearly presented. Because the template is implemented as a Quarto extension, it remains portable and reusable across projects, and can be further modified, particularly by those comfortable with LaTeX, to accommodate journal-specific formatting requirements.

Slides

Researchers often need to present their findings at conferences, seminars, or in teaching settings. Quarto supports multiple presentation formats, including Reveal.js, Beamer, and PowerPoint. In this template, I use Beamer to produce PDF slides, which are widely accepted in academic contexts and easy to share or print.

slides/
├── slides.pdf (not tracked in Git)
└── slides.qmd

The slides/ folder contains the Quarto source file (slides.qmd) and the compiled PDF output (slides.pdf). As with the manuscript, the PDF is treated as a generated artifact and excluded from version control.

The resulting slides are indistinguishable from those produced using a traditional LaTeX Beamer workflow. The key difference is that all content—including code, tables, and figures—can be generated directly from the same analytical pipeline.

In this example, I deliberately reuse the same output objects (e.g., tables and figures) in both the manuscript and the slides. This guarantees consistency across formats and eliminates the risk of discrepancies between what appears in the paper and what is presented publicly.

The example slides also demonstrate practical considerations such as resizing tables and figures to fit slide layouts. They reference the same shared bibliography file used in the manuscript, ensuring consistent citation formatting across outputs. Although only a single reference is included in the example, the template is configured to allow references to span multiple frames, accommodating a realistic bibliography.

README file

README.md

Following both GitHub conventions and academic best practice, every project should include a README.md file. This file serves as the primary entry point for others who wish to understand, reproduce, or build upon the research.

In the template, the README provides:

• A brief project description
• Instructions for setting up the environment
• Steps to reproduce the analysis, manuscript, and slides

Additional placeholders are included for information such as the machine model and operating system used during development. While not always necessary, this metadata can be helpful when troubleshooting platform-specific issues, particularly for projects involving compiled dependencies. The README also notes the approximate time required to run the full analysis and render outputs, which helps set realistic expectations for replication.

Notably, the template does not include a LICENSE file by default. This is intentional. The appropriate license for academic code and data depends on disciplinary norms, institutional policies, journal requirements, and the researcher’s intended level of openness. Common choices include MIT or GPL licenses for code, and Creative Commons licenses for data. In some cases, more restrictive or custom licenses may be appropriate. Researchers should select a license deliberately, ensuring it aligns with their sharing goals and complies with relevant policies.

GitHub as infrastructure — not just hosting

Once a project is structured clearly and pushed to GitHub, it becomes more than a collection of files. It becomes infrastructure.

A well-organized repository makes collaboration dramatically smoother. Issues can serve as lightweight meeting minutes, evolving naturally into task lists. They can be assigned to specific contributors, grouped into milestones, and tracked over time. Pull requests and branching strategies help keep the main branch stable while allowing experimentation and iterative refinement. Code reviews become part of the workflow rather than an afterthought.

These practices, borrowed from software development, translate surprisingly well into academic collaboration. Instead of emailing attachments back and forth, collaborators work against a shared, versioned source of truth.

A clear project structure also makes modern AI tools significantly more useful. When your data, scripts, outputs, and manuscripts are logically organized, AI assistants in VS Code, Positron, or GitHub can reason about your project more effectively. They can trace how tables were generated, suggest improvements to analysis code, help refine writing based on the underlying results, or flag inconsistencies between figures and text. In other words, organization enables context — and context is what makes AI assistance meaningful rather than superficial.

There are also practical benefits. Once your work is version-controlled and backed up remotely, you no longer fear data loss due to a failed hard drive, a stolen laptop, or accidental overwrites. The repository itself becomes a durable record of the project’s evolution.

Perhaps most importantly, a well-structured project reduces the asymmetry of knowledge among collaborators. Instead of each co-author being familiar with only one portion of the workflow, everyone can develop a holistic understanding of how the project fits together — from raw data to final manuscript. This makes feedback more constructive, collaboration more efficient, and the research process more transparent.

Reproducibility, then, is not merely about satisfying journal requirements. It is about building research projects that are resilient, collaborative, and adaptable — projects that scale not only across machines, but across people.

Conclusion

At its core, none of the tools discussed here—Git, renv, Quarto, or GitHub—are revolutionary on their own. What matters is how they are combined into a coherent project structure. Once that structure becomes habitual, reproducibility stops being an afterthought and becomes the default.

Adopting this workflow does not require perfect foresight or advanced technical expertise. It simply requires deciding, from the outset, that clarity, versioning, and regeneration will guide the project. The payoff is substantial: fewer replication headaches, smoother collaboration, better integration with modern tooling, and greater confidence in the durability of your work.

In the long run, a well-structured project is not just easier to reproduce—it is easier to think with.

Quarto 2 is a full rewrite of the Quarto CLI, written from the ground up in Rust to better support your existing use cases, and enable a number of new, exciting use cases. Most importantly, Quarto 2 will include a built-in collaborative editor, and we plan on adding support for collaborative writing in Posit’s commercial products such as Posit Cloud, Connect, and Workbench. With that said, the design of those integrations is still taking shape.

It is also very early in the project. If you interact with the Quarto project solely as a user of the tool, nothing in your workflow will change, and you should proceed as if you didn’t know about our plans for Quarto 2. We don’t expect to have a public release of Quarto 2 for at least 6 months. In addition, we will continue to develop and maintain parallel versions until Quarto 2 is a suitable replacement for users of Quarto 1.

Just like Quarto 1, Quarto 2 is open source and MIT licensed. The GitHub repository for Quarto 2 is currently quarto-dev/q2 .

Why Quarto 2?

There are some fundamental pain points in Quarto 1 that can’t be solved incrementally. The goal of Quarto 2 is not to change how you currently work with Quarto; instead, we’ve arrived at a point where incremental improvements do not provide the value you deserve given our team size and constraints. These are some of the things we want to do in Quarto 2:

• A new Markdown parser enables tighter integration with editors for the entire rendering pipeline. We know that good error messages, autocompletion, and YAML validation are some of your favorite features in Quarto 1. Quarto has about 1,000 different YAML configuration options, and we know how important it is to be able to provide good error messages. We want to extend this same idea to everything in your Quarto project: Markdown syntax errors, Lua filter errors, broken links, etc. Whenever possible, these should be flagged in your editor of choice.

• A fundamental solution for long-standing performance problems. Quarto 1 is built by integrating a number of tools that work very well in isolation, but aren’t designed to be performant when used together. A full rewrite of the Quarto core functionality in a single programming language will enable us to provide much better performance than before.

• A collaborative editor. Quarto 2 will ship with a collaborative editor designed to work directly on the web as well as on the command-line. Keeping in the tradition and ethos of the Quarto project, this will include a robust open-source foundation based on automerge , as well as a commercial solution for hosted project management. This follows the relationship between Quarto 1 and its integration with other Posit commercial offerings.

• A visual editor that works well alongside a source editor. The visual editor we ship in RStudio, VS Code, and Positron works well if everyone working on the document is using the visual editor. On the other hand, if you choose the visual editor, but your colleague chooses the source editor, then you’ll find that the experience is full of sharp edges. Quarto 2 is built from the ground up to support bidirectional editing workflows. A small change in your document using the visual editor shouldn’t cause a large change in the .qmd file that is disruptive for your colleagues using a source editor.

• Support for Quarto 1 projects. We aim for Quarto 2 to be backwards compatible with Quarto 1. Concretely, we’re aiming to incorporate our Quarto 1 test suite directly into Quarto 2’s project, including support for Pandoc and its output formats that our community depends on. Your existing extensions and projects should just work in Quarto 2. Early on, there will be gaps, and Quarto 2 will initially be a better fit for new projects.

What happens to Quarto 1 development?

It’s not going anywhere, and will be in active development for at least the next year. We’ll still provide bugfixes, and accept pull requests.

Current status

The development is happening in a separate GitHub repository . Feel free to look around! However, this code base isn’t ready for public consumption, and is very much in flux: that means we’re not going to spend a lot of time answering architectural questions about it until things have settled, and all discussion of Quarto should remain in our current discussion forum and issue tracker.

There are big, interesting changes in the Quarto 2 architecture, and they deserve a longer exposition. We are working on those documents right now, and will share them with you in the next few weeks. Stay tuned!

The Typst ecosystem is thriving, and Quarto 1.9 brings Typst much closer to feature parity with LaTeX:

• Typst books
• Article layout in Typst
• Bundling of Typst packages for offline rendering

Typst books

In Quarto 1.9, a project with type book and format typst is now rendered as a single document with multiple chapters and other book content.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

project:
  type: book

book:
  title: "My Book"
  author: "Jane Doe"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd

format: typst

All book features previously available in the LaTeX format are now available in Typst:

• Parts and Chapters
• Appendices
• Cross-references and chapter-based numbering
• Table of Contents

List-of-Figures and List-of-Tables support is coming soon .

The default Typst book uses the bundled Quarto quarto-orange-book extension, which uses typst-gather to bundle the Typst orange-book package. Orange-book provides a textbook-style layout with colored chapter headers and sidebars.

The orange-book extension supports brand.yml customization — it uses the primary color for chapter headers and sidebars, and the medium logo on the title page. The screenshots above were generated with this _brand.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

color:
  primary: "#F36619"
  secondary: "#2E86AB"

logo:
  images:
    test-logo:
      path: logo.svg
      alt: "Test Logo"
  medium: test-logo

Since Typst books are implemented as Quarto Format Extensions , you can customize the appearance by creating your own extension. Typst partials define the overall book structure, while Lua filters handle the necessary AST transformations.

Article layout in Typst

Also in Quarto 1.9, all Article Layout features now work in Typst, via the Typst Marginalia package.

Specifically:

• Figures, tables, code listings, and equations can be placed in the margin using the .column-margin class or the column: margin code cell option.
• You can also target specific output types with fig-column: margin or tbl-column: margin.
• Figure, table, and code listing captions can be placed in the margin with cap-location: margin (or fig-cap-location: margin and tbl-cap-location: margin for specific types).
• Footnotes and citations can be displayed in the margin with reference-location: margin and citation-location: margin. When margin citations are enabled, the bibliography is suppressed.
• Asides (.aside class) place content in the margin without a footnote number.

typst-gather

Quarto 1.9 automatically stages Typst packages — from your extensions, from Quarto’s bundled extensions, and from Quarto itself — into the .quarto/ cache directory before calling typst compile. This means Typst documents render offline without needing network access.

To make this work, extension authors use the new typst-gather tool, which scans their .typ files for @preview imports and downloads the packages into the extension directory. Authors run quarto call typst-gather and commit the results. Users of the extension will have the packages staged without any downloads.

This means Custom Typst Formats can depend on Typst packages without copying and pasting Typst code, making them simpler and easier to maintain.

Both Typst books and article layout are built on typst-gather — orange-book depends on the Typst orange-book package, and article layout depends on Marginalia . As the Typst package ecosystem grows, we’re excited to see what the community builds with Typst packages.

Sharing your work just got easier with integrated Posit Connect Cloud publishing. Typst users will appreciate book project support and article layouts, while experimental PDF accessibility standards bring PDF/A and PDF/UA compliance to both LaTeX and Typst. This release also introduces LLM-friendly output for websites, the quarto use brand command for keeping your brand assets in sync, and list tables for authoring complex tables with familiar bullet syntax.

You can read about these improvements and some other highlights below. You can find all the changes in this version in the Release Notes .

Publish to Posit Connect Cloud

You can now publish documents and websites to Posit Connect Cloud directly from the command line. For example, publish your Quarto website project with:

1

quarto publish posit-connect-cloud

Posit Connect Cloud is a hosted platform for sharing data applications and documents without managing your own infrastructure. It includes a free tier for unlimited static document publishing. Read more in Publishing > Posit Connect Cloud .

Improvements to Typst Support

Quarto 1.9 brings substantial improvements to Typst output:

• Book projects can now render to Typst via the bundled orange-book extension, with chapter numbering, cross-references, and professional textbook styling.
• Article layout support lets you place content in the margins, create full-width figures, or add side notes.
• New options: mathfont, codefont, linestretch, linkcolor, citecolor, filecolor, thanks, and abstract-title.
• Theorem styling with four appearance options: simple, fancy, clouds, or rainbow.

See this blog post for details on all the Typst improvements.

PDF Accessibility (Experimental)

We’re rolling out experimental support for PDF accessibility standards in 1.9. The new pdf-standard option enables PDF/A archival formats and PDF/UA accessibility compliance for both LaTeX and Typst outputs. Alt text from fig-alt attributes now passes through to PDF for screen reader support, and Typst gains support for alt text on cross-referenced equations.

Read more in our PDF Accessibility and Standards blog post or the documentation for LaTeX and Typst .

Output for LLMs

Quarto can now generate llms.txt format output for your website, making your content more accessible to large language models and AI-powered tools.

Enable it in your website configuration:

1
2
3

website:
  title: "My Documentation"
  llms-txt: true

When you render your site, Quarto creates:

• An llms.txt index file at the root of your site listing all pages
• A .llms.md markdown file alongside each HTML page (e.g., guide.html gets guide.llms.md)

The markdown files contain clean versions of your content—navigation, sidebars, and scripts are stripped out; tables, code blocks, and callouts are converted to standard markdown.

Read more, including how to customize what appears in LLM output, in Websites > Output for LLMs .

quarto use brand Command

Keep your project’s brand assets in sync with an external source using the new quarto use brand command:

1

quarto use brand myorg/shared-brand

The command copies brand files from a GitHub repository, local directory, or zip archive into your project’s _brand/ directory. Quarto walks you through each step—confirming trust for remote sources, creating the directory if needed, and asking whether to overwrite or remove files.

See Guide > Brand for --dry-run, --force, and other options.

List Tables

List tables provide a new syntax for creating tables with complex content—multiple paragraphs, code blocks, or nested lists—using familiar bullet syntax instead of grid table formatting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

::: {.list-table}
- - Function
  - Description

- - `sum()`
  - Add values:

    ```python
    sum([1, 2, 3])
    ```

- - `len()`
  - Count items:

    - Works on lists
    - Works on strings
:::

sum([1, 2, 3])

Each top-level bullet represents a row; nested bullets represent cells. This syntax is much easier to maintain than grid tables, especially when cells contain code or other block elements.

List tables support all the usual table features: captions, cross-references, column widths, and alignment. Thanks to Martin Fischer for the original development, with contributions from Albert Krewinkel and William Lupton.

Find all the details in Guide > Tables .

Other Highlights

• Search Result Highlighting : Improved highlighting of search terms on destination pages, with persistent marks, automatic tab activation for matches inside tabsets, and cross-element highlighting for multi-word searches.

• Privacy-focused features for websites:

  • A privacy-first default for cookie consent : The default for cookie consent has changed to type: express, providing opt-in consent that blocks cookies until users explicitly agree. This privacy-conscious default is designed with modern privacy regulations in mind.

  • Algolia Search Insights avoids cookies : Use Algolia Insights now uses persistent cookies only if cookie-consent is active, and the user has opted-in.

  • Use Plausible Analytics : Add privacy-friendly Plausible Analytics to websites via the plausible-analytics configuration option.

• aria-label for videos : Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default “Video Player” label.

• New syntax-highlighting Option : Replaces the deprecated highlight-style (Pandoc 3.8). Supports style names, custom .theme files, none, or idiomatic for format-native highlighting.

• Metadata and brand extensions now work without a _quarto.yml project. A temporary default project is created in memory.

• Engine extensions allow replacement of the execution engine:

  • Julia is now a bundled extension instead of being built-in.
  • quarto-marimo will soon change from a filter extension to an engine extension.
  • New quarto create extension engine command.
  • New quarto call build-ts-extension command.
  • New Quarto API for engine extensions to use. (This is in flux and will not be documented for the next few releases, but there is a dev blog post about it .)

Dependency updates:

• pandoc updated to 3.8.3
• typst updated to 0.14.2
• esbuild updated to 0.25.10
• deno updated to 2.4.5
• mermaid updated to 11.12.0

Acknowledgements

One of the early proposals for PDF accessibility and alt text in the LaTeX ecosystem was provided to us by Sam Schiano and Sophie Breitbart . We want to thank them for bringing into our attention the approach they used in their {asar} R package , which influenced some of our design.

In addition, we’d like to say a huge thank you to everyone who contributed to this release by opening issues and pull requests:

CoryMcCartan , DanChaltiel , Data-Wise , FrankwaP , Joao-O-Santos , LukasDSauer , MBe-iUS , MarcoPortmann , MariaBarrioSchez , MateusMolina , Selbosh , ThePurox , TucoFernandes , aecoleman , amirhome61 , andrewheiss , azankl , bensoltoff , bruvellu , byzheng , cbrnr , chendaniely , chi-raag , christopherkenny , coatless , cynthiahqy , darwindarak , davidskalinder , dmenne , fconil , fkgruber , fkohrt , fredguth , gadenbuie , github-actions[bot] , gsathler-vi , hamgamb , herosi , icarusz , idavydov , jeremy886 , jkrumbiegel , jmcphers , jonas37 , jorherre , jreades , jromanowska , jtbayly , juleswg23 , juliasilge , kathsherratt , kusnezoff-alexander , lrrichter , lwjohnst86 , maelle , matthiasbaitsch , mipmip , mstrms2000 , multimeric , mvuorre , mykolaskrynnyk , nichtich , nithinmkp , nrichers , orbsmiv , paytonej , petrelharp , phongphuhanam , pm-gusmano , posit-snyk-bot , prosoitos , rabyj , sasja-san , sbwiecko , serialc , spaette , spraetor , stragu , szimmer , the-solipsist , thomasp85 , yyzeng , zhe00a .

The airplane departure emoji in the listing and social card image for this post comes from OpenMoji– the open-source emoji and icon project. License: CC BY-SA 4.0

2025 was a big year for PDF accessibility. LaTeX and Typst both released support for PDF tagging and accessibility standards, just in time for new regulations in the EU (June 2025) and US (April 2026).

Quarto 1.9 brings this support to you as a Quarto user.

What PDF Standards Do

Currently LaTeX supports the newer UA-2 standard, and Typst supports the older UA-1 standard. Typst is likely to have UA-2 support later in 2026.

Both standards instruct the PDF renderer to provide screen readers:

• The semantic structure of the text (title, heading, paragraph, figure, etc)
• The natural reading order
• Spatial coordinates for highlighting and assistive navigation
• Required metadata such as title and language

How to enable a PDF Standard in Quarto

In Quarto 1.9, specify a PDF standard for your document or project with pdf-standard

1
2
3

format:
  pdf:
    pdf-standard: ua-2

1
2
3

format:
  typst:
    pdf-standard: ua-1

pdf-standard takes a single standard name or list of standard names. PDF version is used if provided in the list, but otherwise inferred from the standard.

If you specify a PDF standard, Quarto first instructs LaTeX or Typst to use the standard when producing the PDF, and then validates the output PDF against the standard using veraPDF, an open-source PDF validation tool. If veraPDF is not installed, you’ll get a warning but still receive a PDF – it just won’t be validated.

1

quarto install verapdf

When a document passes validation, you’ll see output like:

[verapdf]: Validating my-document.pdf against PDF/UA-2... PASSED

Creating accessible PDFs

Quarto’s Markdown-based workflow handles many accessibility requirements automatically:

• Document metadata (title, author, date, language) flows into the PDF’s built-in metadata fields.
• The semantic structure of Markdown satisfies PDF tagging requirements. For Typst this is always enabled; for LaTeX it is enabled when you specify a standard that requires it.
• Alt text for images is carried through to the PDF for screen readers.

But you do need to make sure your document has:

• A title in the YAML front matter.
• Alt text for every image, specified with fig-alt. See Figures for details.

See the LaTeX and Typst documentation for more details.

If your document fails validation

LaTeX does not perform validation during PDF generation, so if veraPDF validation fails, that’s a warning, and you still get a partially-accessible PDF as long as you use pdf-standard: ua-2.

Typst fails and does not produce a PDF if its built-in validation fails during PDF generation. However, in Typst all accessibility features are on by default, so you can generate a partially-accessible PDF by rendering without pdf-standard.

Current limitations

We ran our test suite – 188 LaTeX examples and 317 Typst examples – to find where Quarto PDFs do not yet pass UA-1 or UA-2, and where users will need to change their documents.

LaTeX

Margin content is the biggest structural blocker. If you use .column-margin divs, cap-location: margin, reference-location: margin, or citation-location: margin, the resulting PDF will not pass UA-2. The underlying sidenotes and marginnote LaTeX packages do not cooperate with PDF tagging .

(Margin content does work with Typst and passes UA-1 – see Typst Article Layout .)

There are smaller upstream issues in Pandoc, LaTeX, and LaTeX packages, documented here .

Typst

In our tests, Typst catches every UA-1 violation, and fails to generate the PDF. veraPDF did not detect any violation that Typst did not.

Typst also seems to do a very good job of generating UA-1 compliant output by default – almost all errors were due to missing titles or missing alt text.

However, we did discover that Typst books are not yet compliant. There is a structural problem with the Typst orange-book package and we’ll work with the maintainers to correct it.

Conclusion

Although Typst currently targets an the earlier UA-1 standard, today it seems to offer better PDF accessibility than LaTeX.

We expect PDF accessibility support to improve through the LaTeX ecosystem throughout 2026 as awareness of UA-2 and the new regulations spreads.

If you run into accessibility issues with PDF output, please search the Quarto discussions and open a new one with the accessibility label for any issues you discover.

Talks included in the playlist, broken up into a few categories for easier browsing, are as follows:

Quarto Extensions & Advanced Features

Speakers	Title	Thumbnail
Carlos Scheidegger (Quarto Team)	What we’re doing to make Quarto fast(er)
Christophe Dervieux (Quarto Team)	Beyond the Basics: Expanding Quarto’s Capabilities
Garrick Aden-Buie	Theming Made Easy: Introducing brand.yml
Gordon Woodhull (Quarto Team)	Brand YML and Dark Mode in Quarto
JooYoung Seo	maidr: Empowering Accessible, Multimodal Data Science with Quarto

Workflow Automation & Reporting

Speakers	Title	Thumbnail
Becca Krouse	Instant Impact: Developing {docorator} to Simplify Document Production
John Paul Helveston	surveydown: A Markdown-Based Platform for Interactive Surveys
Keaton Wilson	Using Quarto to Improve Formatting and Automation

Teaching & Education

Speakers	Title	Thumbnail
Claus Wilke	Teaching data visualization with R entirely in Quarto
Mine Çetinkaya-Rundel (Quarto Team)	Leveraging LLMs for student feedback in introductory data science courses
Ted Laderas	Empowering Learners with WebR, Pyodide, and Quarto

Business, Collaboration & Publishing

Speakers	Title	Thumbnail
Andrew Heiss and Gabe Osterhout	Election Night Reporting Using R & Quarto
Bill Pikounis	Quarto for Business Collaboration and Technical Documentation in Word docx format
Timothy Keyes	Trust, but Verify: Lessons from Deploying LLMs

We hope you enjoyed this look back at the Quarto sessions from posit::conf(2025). Every year the community brings new ideas, new tools, and new ways of working — and we’d love to see your voice added to the mix. We hope to see you next year, and maybe even see you up on stage sharing your own work at posit::conf!

All materials from both workshops are available online. You can access the full workshop websites, source code, and exercises to learn at your own pace or adapt them for your own teaching; they are both released with a CC BY-SA 4.0 license.

Branded Websites, Presentations, Dashboards, and PDFs with Quarto

Workshop website Source Exercises

Led by Isabella Velásquez , Posit, PBC and Sara Altman , Posit, PBC.

Designed for data scientists, analysts, and content creators, this immersive session will teach you how to craft cohesive reports and presentations while refining your workflow with Quarto’s latest features.

You will learn how to create dynamic websites, professional PDF documents, engaging presentations, and interactive dashboards using Quarto. This workshop highlights Quarto’s powerful theming capabilities, including the new support for brand.yml, which ensures that your work maintains a professional and cohesive style across all formats.

By the end of the session, you’ll be equipped to:

• Build and deploy Quarto websites.
• Generate professional presentations and PDF reports.
• Create interactive dashboards for data visualization and reporting.
• Use brand.yml to define and apply consistent theming across all outputs.

Whether you’re looking to enhance your personal projects or streamline organizational outputs, this workshop will equip you with the tools to create polished, professional results.

Extending Quarto

Workshop website Source Exercises

Led by Mine Çetinkaya-Rundel , Posit, PBC + Duke University and Charlotte Wickham Posit, PBC.

In this workshop, we will dive deep into ways of customizing your Quarto outputs with tooling beyond built-in features. This workshop is designed for data scientists, analysts, and technical writers looking to extend Quarto’s capabilities to suit their unique workflows better.

Participants will learn how to create custom extensions, including new formats, templates, and filters, to enhance their document production process. Through hands-on exercises and real-world examples, you’ll gain practical skills in:

• Developing and integrating custom formats to support diverse outputs while reducing repetition across projects.
• Substituting Quarto’s templates with your own to customize formats beyond the built-in options.
• Implementing filters to automate and streamline content transformation.

By the end of the workshop, you will be able to leverage Quarto’s extensibility to create powerful, tailored solutions for your documentation needs. Whether you have just worked on a few Quarto projects or are an everyday user, this workshop will equip you with the tools and knowledge to take your document workflows to the next level.

I’m absolutely thrilled to announce Quarto Wizard 1.0.0, a groundbreaking extension for Visual Studio Code and Positron that transforms how you interact with the Quarto ecosystem. If you’ve ever found yourself wrestling with command-line extension management or struggling to discover the perfect template for your project, this tool is about to become your new best friend.

Install it today from the VS Code marketplace or Open VSX Registry :

Quarto has revolutionised scientific and technical publishing by enabling reproducible documents that seamlessly blend code, narrative text, and visualisation. However, one persistent friction point has been managing the rich and ever-growing ecosystem of extensions and templates—until now.

Quarto Wizard: Your GUI for Quarto extensions

I designed Quarto Wizard to address a fundamental challenge I’ve observed in the community: whilst Quarto’s command-line interface is powerful, many users prefer visual interfaces for discovering, installing, and managing extensions.

Seamless IDE integration

Quarto Wizard integrates beautifully with both the VS Code and Positron ecosystems, appearing as a dedicated icon in the Activity Bar alongside your other development tools. This provides instant access to extension management without disrupting your coding flow, whether you’re in Microsoft’s VS Code or Posit’s new Positron IDE.

The solution is multi-modal installation: you can now install extensions through multiple pathways that suit your workflow: from the command line, through the web directory, or via the Quarto Wizard GUI in your IDE.

Intelligent extension management

The “Recently Installed Extensions” feature helps track your workflow and easily reproduce project setups across different environments. This is invaluable for researchers collaborating across multiple machines or teaching workshops where consistent setups are essential, regardless of whether team members use VS Code or Positron.

What makes this particularly powerful is that Quarto Wizard tracks which extensions were installed through its interface by adding source metadata to the _extensions.yml file, enabling seamless updates and removals.¹ This source tracking transforms extension maintenance from manual archaeology into an effortless workflow. The extension maintains detailed metadata about installed extensions, enabling batch operations and dependency tracking. The Explorer View provides a comprehensive overview of all installed extensions with visual indicators for updates and management options.

Template workflow simplified

Beyond extension management, I’ve designed Quarto Wizard to ease the process of discovering and using document templates. Once you’ve selected a template, Quarto Wizard lets you customise and save the document. The file is not created until you confirm, allowing you to adjust the filename and location.

Powered by a comprehensive extension directory

A curated catalogue of 250+ extensions

At the heart of Quarto Wizard lies the Quarto Extensions directory (m.canouil.dev/quarto-extensions/) , a comprehensive listing I maintain that catalogues extensions from across the entire Quarto ecosystem.

To date, it includes over 250 extensions contributed by the community, covering a vast array of functionalities from citation management to interactive visualisations. This directory powers Quarto Wizard’s discovery features, providing rich metadata about each extension including descriptions, licensing, version tags, and GitHub stars. The directory is continuously updated through GitHub’s API, ensuring you always have access to the latest extensions from the community.

One-click installation from the web

What’s particularly exciting is that you can install extensions or use templates directly from the website itself. Each extension listed at m.canouil.dev/quarto-extensions/ includes multiple installation options: traditional command-line via terminal, or one-click installation through Quarto Wizard in VS Code, Positron, or VSCodium. Simply browse the directory, find the extension you need, and choose your preferred installation method. The website generates the appropriate commands or launches your IDE directly. This flexibility means teams with mixed technical backgrounds can all access the same powerful extensions.

For example, you might want to add the Iconify extension to access over 200,000 open source vector icons in your documents, or the Animate extension to bring your presentations to life with CSS animations. Perhaps the Spotlight extension for Reveal.js catches your eye for creating dramatic Reveal.js presentations that highlight your mouse position. All of these extensions (and hundreds more) are just a click away.

Template discovery made easy

Additionally, the Quarto Extensions directory excels at template discovery and deployment which is enhanced with powerful filtering options: you can sort by recently updated, filter by popularity, browse by categories (i.e., Shortcodes, Filters, Formats, Projects, Reveal.js Plugins), or search for specific functionality. Each extension clearly indicates whether it’s a template with “Use” buttons alongside “Install” options.

Whether you’re crafting an academic paper using journal-specific formats, creating professional invoices with my Invoice extension template, or building stunning presentations with themed templates like my Reveal.js Coeos extension, browsing available templates becomes as simple as scrolling through a curated gallery.

This directory creates a seamless experience: instead of manually searching GitHub repositories or memorising command-line syntax, you can browse hundreds of extensions with detailed information at your fingertips. This transforms extension discovery from a treasure hunt into a curated shopping experience.

Addressing real workflow friction

I designed Quarto Wizard and the extension directory at m.canouil.dev/quarto-extensions to directly tackle several persistent Quarto pain points I’ve encountered:

• Discovery challenges: Finding relevant extensions in the growing ecosystem becomes intuitive through the visual browser interface powered by the comprehensive extensions directory.

• Command-line intimidation: Users who prefer graphical interfaces no longer need to memorise terminal commands.

• Document setup complexity: Template-based document initialisation eliminates manual YAML configuration.

• Extension maintenance: Updates, removals, and dependency management become point-and-click operations rather than command-line archaeology.

• Source tracking: Quarto Wizard automatically adds source metadata to installed extensions, enabling future updates and proper version management.

• Stable installations: Quarto Wizard installs extensions from GitHub releases/tags by default instead of the potentially unstable default branch, ensuring more reliable installations and more replicable environments.

Perfect for diverse use cases

The extension shines across multiple scenarios:

• Academic researchers can quickly install citation management tools, bibliography extensions like Multibib or Section Bibliographies , and journal-specific formatting, whether they’re using VS Code or Positron for their analysis work.

• Data scientists gain easy access to computational extensions like WebR , visualisation tools, and interactive notebook capabilities. This is particularly powerful in Positron, which is designed specifically for data science workflows.

• Technical writers can browse and install extensions for enhanced typography with for example the Highlight Text extension for multi-format text highlighting, code highlighting, and advanced formatting options of their Reveal.js presentations with Reveal.js Editable extension in their preferred IDE.

• Workshop instructors can ensure all participants have consistent extension setups through guided installation processes, regardless of whether attendees prefer VS Code or Positron.

Future-ready architecture

I’ve built Quarto Wizard on robust foundations that ensure long-term reliability. The extension integrates with GitHub’s API through the Quarto Extensions directory for real-time metadata, includes attestation verification for security, and maintains full compatibility with both VS Code and Positron environments.

The modular architecture allows for future enhancements whilst maintaining backwards compatibility. As the Quarto ecosystem continues expanding and as Positron evolves alongside VS Code, Quarto Wizard will support new extension types and project management workflows in both environments.

Getting started today

Begin your Quarto Wizard journey by installing the extension from the VS Code marketplace, the Open VSX Registry, or directly through your IDE’s Extensions view. Once installed, the Quarto Wizard icon appears in your Activity Bar, providing immediate access to extension management and project tools.

You have multiple paths to explore Quarto extensions:

1. Through Quarto Wizard: Click the Quarto Wizard icon in your IDE’s Activity Bar and browse the integrated catalogue.
2. Via the web directory: Visit m.canouil.dev/quarto-extensions where you can browse all extensions and install them directly from the website. Each extension offers installation buttons for Quarto Wizard, VS Code, Positron, VSCodium, or traditional terminal commands.
3. Traditional command-line: Use the familiar quarto add commands if you prefer.

Try installing your first extension: perhaps Iconify extension for comprehensive icon support or GitHub for seamless GitHub linking. Whether you click “Install” on the website, use Quarto Wizard’s interface, or type commands in the terminal, the choice is yours. The difference in experience compared to traditional command-line installation is immediately apparent, especially when browsing the visual catalogue with its filtering options, popularity indicators, and rich metadata.

I believe Quarto Wizard represents a significant step forward in making Quarto’s powerful publishing capabilities accessible to users regardless of their comfort level with command-line tools or their choice of IDE. By providing intuitive visual interfaces for complex operations, Quarto Wizard democratises access to the rich Quarto ecosystem whilst maintaining the flexibility and power that makes Quarto exceptional.

The future of reproducible publishing is here, and it’s more accessible than ever in whichever modern development environment you prefer.

Quarto 1.8 improves support for light and dark brand colors and logos, brand extensions for sharing brands across Quarto projects, HTML accessibility checks powered by Axe-core, and access to more information about execution context from your code cells. You can read about these improvements and some other highlights below. You can find all the changes in this version in the Release Notes .

Dark and light colors and logos in brand

You can now specify light and dark versions of any colors or logo in a brand specification:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

color:
  foreground:
    light: "#333333"
    dark: "#EEEEEE"
  background:
    light: "#EEEEEE"
    dark: "#333333"
logos:
  medium:
    light: logo.png
    dark: logo-white.png         

This works in _brand.yml files as well as brand specified directly in document metadata. You can also present in dark mode by specifying brand-mode: dark in your format: revealjs presentations.

Read more in the updated Guide > Brand :

• Light and dark colors
• Light and dark logos
• Brand mode

Brand extensions

Share brand definitions and assets across Quarto projects with a brand extension.

Get started with:

quarto create extension brand

Read more in Extensions > Brand , and keep an eye out for other ways to reuse and share your brand in future releases.

Accessibility checks for HTML

You can add accessibility checks using the Axe-core engine to HTML documents (format: html, revealjs and dashboard) with the new axe option.

For example, you can get a summary of violations right in your document preview:

Read about your options in HTML Accessibility Checks

We know accessability is a big concern for many of our users, and more improvements will be coming in future releases.

Accessing execution information

Quarto sets the QUARTO_EXECUTE_INFO environment variable, which allows you to access information about execution context from code cells.

Read the JSON file located at QUARTO_EXECUTE_INFO and access properties such as document-path, format, metadata and more:

1
2
3

library(jsonlite)
execute_info <- read_json(Sys.getenv("QUARTO_EXECUTE_INFO"))
execute_info$`document-path`

1
2
3
4
5
6

import json
import os

with open(os.getenv("QUARTO_EXECUTE_INFO")) as f:
    execute_info = json.load(f)
execute_info["document-path"]

1
2
3
4

using JSON

execute_info = JSON.parsefile(ENV["QUARTO_EXECUTE_INFO"])
execute_info["document-path"]

Read more in Access execution settings from code cells .

Other Highlights

• Access metadata and variables in filters and shortcodes: Use the new quarto.variables.get() and quarto.metadata.get() APIs.

• The default LaTeX engine is now lualatex.

Dependency updates:

• mermaidjs updated to 11.6.0.
• Bootstrap icons updated to v1.13.1
• QuartoNotebookRunner in julia engine updated to 0.17.3

Acknowledgements

We’d like to say a huge thank you to everyone who contributed to this release by opening issues and pull requests:

Aariq , AndreasThinks , ArthurData , Blake-Madden , ColinFay , DCEW , DanStuder , Data-Wise , EllaKaye , EmilHvitfeldt , FrankwaP , GabrielCoffee9 , GeorgRamer , Gewerd-Strauss , GuillaumeDehaene , HarunCelikOtto , HayesJohnD , Joao-O-Santos , MateusMolina , MichaelHatherly , PeteArm , Selbosh , SergeCroise , SrShelo , VisruthSK , Vistales , abhiaagarwal , aborruso , adamblake , adamiturabi , alastairrushworth , albertomercurio , alecloudenback , alex-r-bigelow , allefeld , alyst , andrewheiss , andrewpbray , austin-hoover , batpigandme , bauerj , benkeks , benz0li , bkowshik , blackerby , boshek , brandonmontez , bryce-carson , carschandler , christopherkenny , cl-roberts , cmadland , co1emi11er2 , coatless , cpcloud , daxkellie , dixslyf , dkapitan , econmaett , edavidaja , edvinsyk , ethanwhite , fermarsan , fredguth , fuhrmanator , gadenbuie , georgestagg , ghisvail , ghost , github-actions[bot] , glin , gregswinehart , gwbrck , halleysfifthinc , hansfn , hchulkim , holtzy , htbunn , hturner , hugetim , hutch3232 , iagopinal , ihrke , jameslairdsmith , jdfoote , jeremy9959 , jfy133 , jkrumbiegel , jmgirard , jonpeake , jvcarli , jxpeng98 , kandolfp , kapsner , kathsherratt , kazuyanagimoto , kevinah95 , kippandrew , koldle , lachlansimpson , lbm364dl , leovuong , lostmygithubaccount , lu-kas , lukmanaj , lwjohnst86 , maelle , mahmudstat , masud90 , melaniewalsh , mfisher87 , mipmip , mpr1255 , multimeric , musvaage , mvuorre , nathanj3 , nessan , nichtich , odysseu , ofkoru , olivroy , oyvindbso , pagiraud , parmsam , peter-gy , pm-gusmano , produnis , rabyj , raffaem , randyzwitch , rben01 , rossbowen , rundel , ryanzomorrodi , ryjohnson09 , s2t2 , salim-b , samcarter , serialc , sgelzenleuchter , skriptum , spaette , stragu , sun123zxy , sverrirarnors , tecosaur , temospena , thatchermo , topepo , tylere , winniehell , wklimowicz , yogabonito , youcc , yves-amevoin , yyzeng .

The lightbulb emoji in the listing and social card image for this post comes from OpenMoji– the open-source emoji and icon project. License: CC BY-SA 4.0

What’s New

Install the latest version from CRAN:

1

install.packages("quarto")

Major features in this release include:

• Pass R values to Quarto metadata - Set metadata programmatically based on computed values from knitr engine
• Insert Markdown in HTML tables for Quarto processing - Include Markdown content (equations, links, formatting) in HTML tables
• Apply Light and Dark Themes to Plots and Tables - Change the background and foreground colors of plots and tables based on light & dark themes
• Work with R scripts and Quarto - Extract R code from Quarto documents or prepare R scripts for Quarto rendering
• Build paths from Quarto Project - Build paths relative to Quarto project root within R cells
• Automate Quarto CLI from R - New and improved wrappers around Quarto CLI features for easier automation

Pass R Values to Quarto Metadata

Set metadata dynamically based on R computations with write_yaml_metadata_block(). For example, you could check a parameter value, and conditionally include content based on it:

1
2
3
4
5

#| output: asis

write_yaml_metadata_block(
  is_france = params$country == "france"
)

This will write the following (e.g., when quarto render report.qmd -P country:france):

1
2
3

---
is_france: true
---

Then use Quarto’s conditional features:

1
2
3
4
5
6

::: {.content-visible when-meta="is_france"}
## Fun fact about France

In 2025, France is the most visited country in the world, attracting over 89 million tourists annually!

:::

Improved YAML 1.2 Compatibility

The function now correctly handles special edge cases in YAML quoting. Specifically, it automatically quotes octal-like strings that are not supported in YAML 1.1 (like "0888" or "0999"):

1
2
3
4
5

# These octal-like values are automatically quoted to prevent errors
write_yaml_metadata_block(
  code1 = "0888",    # Without quoting: YAML 1.2 interprets as 888 (invalid octal ignored)
  code2 = "0999"     # Without quoting: YAML 1.2 interprets as 999 (invalid octal ignored)
)

Without the automatic quoting, these values would be interpreted as decimal numbers (888 and 999) in YAML 1.2, losing the leading zeros. This could break code that expects string values like file permissions or ID codes that must preserve leading zeros.

This change applies to internal functions that write YAML from R object lists, and so this improvement is particularly important when using execute_params with quarto_render(), where parameter values might include such edge cases:

1
2
3
4
5
6

# Parameters with octal-like codes are now handled correctly
quarto_render("report.qmd", 
  execute_params = list(
    site_code = "0888",
    permission = "0755"
  ))

For explicit control over quoting, use yaml_quote_string():

1
2
3
4
5

# Force specific values to be quoted in YAML output
metadata <- list(
  code1 = yaml_quote_string("1.0")
)
write_yaml_metadata_block(.list = metadata)

This will mark the string to be double quoted in YAML, preserving the character representation exactly as provided.

See more examples in the dynamic metadata vignette , including how to make parameters available as metadata for conditional content.

Insert Markdown in HTML Tables for Quarto Processing

Quarto can parse Markdown content in HTML tables , enabling rich formatting like math equations, links, and text styling. The new tbl_qmd_*() functions make this powerful Quarto feature easier to use from R:

1
2
3
4
5
6
7
8
9

data.frame(
  Feature = c("Formatting", "Math", "Links"),
  Example = c(
    tbl_qmd_span("**Bold**, *italic*"),
    tbl_qmd_span("$E = mc^2$"),
    tbl_qmd_span("[Quarto docs](https://quarto.org)")
  )
) |>
  knitr::kable(format = "html", escape = FALSE)

These helper functions wrap content in HTML spans with data-qmd-base64 attributes that Quarto recognizes for Markdown processing. They work with any table package that supports raw HTML (knitr, kableExtra, DT). For content that only works in Quarto, use the display argument for graceful fallback. See more examples in the Markdown in HTML tables vignette , including comparisons of Markdown support in HTML tables across different packages.

Apply Light and Dark Themes to Plots and Tables

The theme_colors_flextable(), theme_colors_ggplot2(), theme_colors_gt(), theme_colors_plotly(), theme_colors_thematic() helper functions change the background and foreground colors of six popular plot and table packages. These can be used to produce light and dark renderings to match the plot or table with themes in light and dark mode.

The usage of the the results of these functions depends on the package. See the Theme Helpers article for usage examples of theme_colors_*.

The theme_brand_flextable(), theme_brand_ggplot2(), theme_brand_gt(), theme_brand_plotly(), theme_brand_thematic() helper functions change the background and foreground colors of these packages using corresponding brand.yml colors. See the Light & Dark Renderings Examples for usage examples of theme_brand_*.

Work with R Scripts and Quarto

Extract R Code from Quarto Documents

The new qmd_to_r_script() function provides an alternative to knitr::purl() that leverages quarto inspect for code extraction:

1
2
3
4
5

# Extract R code from a Quarto document
qmd_to_r_script("analysis.qmd")  # Creates "analysis.R"

# Specify custom output
qmd_to_r_script("analysis.qmd", script = "extracted-code.R")

This function uses Quarto’s static document analysis rather than R evaluation, making it faster and safer for simple code extraction. It preserves cells options, commenting cells with eval: false, and ignoring content having purl: false. For documents using advanced knitr features like child= chunks or knitr::read_chunk(), knitr::purl() remains the recommended approach as it handles these through actual document processing.

Prepare R Scripts for Quarto Rendering

Quarto can render R scripts directly , treating specially formatted comments as Markdown. The add_spin_preamble() function helps prepare R scripts for this feature by adding the required YAML metadata:

1
2
3
4
5
6
7

# Add metadata for rendering
add_spin_preamble("analysis.R", 
                  title = "Analysis Report",
                  preamble = list(author = "Data Team"))

# Now render the script with Quarto
quarto_render("analysis.R")

This function adds a minimal spin-style preamble (using #' comments) that Quarto recognizes:

1
2
3
4
5
6
7

#' ---
#' title: Analysis Report
#' author: Data Team
#' ---
#'

# Your original R code follows...

The preamble enables Quarto’s engine binding to properly process the script, allowing you to use R scripts as source documents alongside .qmd files. Learn more about working with R scripts in the R scripts vignette .

Build Paths from Quarto Project

Quarto sets environment variables during rendering that identify the project root, but knitr doesn’t have direct access to this information by default. The new project navigation functions bridge this gap:

1
2
3
4
5

# Build paths relative to the Quarto project root
data_file <- project_path("data", "analysis.csv")

# Explicitly find the project root (searches for _quarto.yml)
root <- find_project_root()

project_path() intelligently handles different execution contexts:

• During quarto render, it uses QUARTO_PROJECT_ROOT or QUARTO_PROJECT_DIR environment variables
• In interactive sessions, it automatically detects the project root by searching for _quarto.yml.
• Falls back to the current working directory with a warning if no project is found.

This ensures your paths work consistently without hardcoding or manual adjustments. For example, you can read a CSV file relative to your project root:

1
2

# In posts/2025/analysis/report.qmd, this resolves to ../../../data/results.csv
results <- read.csv(project_path("data", "results.csv"))

For more explicit control, consider using here::i_am() and here::here() as an alternative approach. Follow r-lib/usethis Issue #128 for improved support in next versions of here.

Automate Quarto CLI from R

The quarto R package has always been designed as a comprehensive wrapper for the Quarto CLI, enabling seamless integration of Quarto into R workflows and pipelines. This release strengthens that foundation with improved wrappers and new helpers.

Extension Management

Programmatically manage Quarto extensions:

1
2
3
4
5
6
7
8

# Add an extension
quarto_add_extension("quarto-journals/jss")

# List installed extensions
quarto_list_extensions()

# Remove an extension
quarto_remove_extension("jss")

Project and Version Management

New helpers for common CLI tasks:

1
2
3
4
5

# Create projects from templates
quarto_create("article", name = "my-analysis")

# Check if a newer version of Quarto is available
check_newer_version()

Document Inspection

Leverage quarto inspect results to answer questions about documents:

1
2
3
4

# Check if a document has parameters (uses quarto inspect internally)
if (has_parameters("report.qmd")) {
  quarto_render("report.qmd", execute_params = list(year = 2025))
}

These CLI wrappers enable automation scenarios like CI/CD pipelines, batch processing, and dynamic project management—all from within R. The consistent interface means you can script complex Quarto workflows without leaving your R environment.

Additional Improvements

Familiar Workflows for Blogdown Users

The new_blog_post() function provides a familiar workflow for users transitioning from blogdown:

1
2

# Create a new blog post with automatic date prefix and YAML frontmatter
new_blog_post("my-first-quarto-post", dir = "posts")

Similar to blogdown’s new_post(), this function automatically creates a new blog post file with proper YAML frontmatter in the appropriate directory structure for Quarto blogs, making the transition from blogdown to Quarto smoother.

Migration Helper for Bookdown Projects

The detect_bookdown_crossrefs() function helps identify bookdown cross-reference syntax that needs conversion:

1
2

# Scan your bookdown project for cross-references
detect_bookdown_crossrefs("my-bookdown-project/")

The function prints detailed guidance to the console, showing:

• Which cross-reference patterns need manual conversion
• Which patterns can be automatically converted
• Specific examples from your files

Example output from the bookdown book sources:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

> detect_bookdown_crossrefs("~/Documents/DEV_R/bookdown/inst/examples", verbose = FALSE)
ℹ Scanning for bookdown cross-references in 12 .Rmd files...
! Found 110 bookdown cross-references that should be converted:

• 01-introduction.Rmd: 3 references
- 3 Sec

• 02-components.Rmd: 52 references
- 5 Eq
- 7 Fig
- 1 Lem
- 1 Lemma Div
- 7 Numbered Equation
- 17 Sec
- 5 Tab
- 5 Theorem Div
- 4 Thm

• 03-formats.Rmd: 20 references
- 4 Fig
- 16 Sec

• 04-customization.Rmd: 5 references
- 5 Sec

• 05-editing.Rmd: 8 references
- 3 Fig
- 5 Sec

• 06-publishing.Rmd: 8 references
- 3 Fig
- 5 Sec

• 08-usage.Rmd: 3 references
- 3 Sec

• index.Rmd: 11 references
- 11 Sec

ℹ Summary of conversion requirements:
• 5 Eq reference
• 17 Fig reference
• 1 Lem reference
• 1 Lemma Div reference
• 7 Numbered Equation reference
• 65 Sec reference
• 5 Tab reference
• 5 Theorem Div reference
• 4 Thm reference

ℹ Manual conversion requirements:
• Section headers: 65 references need manual attention
• Figure labels: 17 references need manual attention
• Table labels: 5 references need manual attention
• Equation structure: 7 references need manual attention
• Theorem blocks: 6 references need manual attention

ℹ For detailed conversion guidance, run: quarto::detect_bookdown_crossrefs("~/Documents/DEV_R/bookdown/inst/examples", verbose = TRUE)

For converting chunk headers from curly brace syntax to Quarto’s YAML style, remember that knitr::convert_chunk_header() is available:

1
2
3
4
5
6
7

# Convert {r label, option=value} to YAML-style chunk options for a single file
knitr::convert_chunk_header("analysis.Rmd", output = NULL)

# To process multiple files in a directory, you need to iterate:
rmd_files <- list.files("my-bookdown-project/", pattern = "\\.Rmd$", 
                        full.names = TRUE, recursive = TRUE)
lapply(rmd_files, knitr::convert_chunk_header, output = NULL)

Together, these tools address the main syntax differences when migrating from bookdown to Quarto.

Enhanced Workflow

• quarto_preview() now returns the preview URL for automation
• Better debugging with QUARTO_R_DEBUG=TRUE environment variable
• Consistent R version usage in embedded processes

Breaking Changes

Output File Handling

The output_file parameter in quarto_render() now sets the output-file metadata field instead of passing the --output CLI flag to Quarto. This change better aligns with Quarto’s metadata processing and enables support for multiple output formats:

1
2

# Sets output-file metadata (like having 'output-file: report.html' in YAML)
quarto_render("doc.qmd", output_file = "report.html")

If you specifically need the old CLI flag behavior, use quarto_args:

1
2

# Use CLI flag directly
quarto_render("doc.qmd", quarto_args = c("--output", "report.html"))

Template Usage

quarto_use_template() now requires an empty directory and fails with a clear error message when used in non-empty directories:

1
2
3

# Create an empty directory first
dir.create("my-article")
quarto_use_template("quarto-journals/jss", dir = "my-article")

This change follows a Quarto CLI update that removed interactive prompting for programmatic use. If you need to use templates in existing directories, use quarto use template directly in the terminal for interactive installation.

Learn More

Explore the new features and improvements:

• Documentation for R package: https://quarto-dev.github.io/quarto-r/
• Full changelog: https://quarto-dev.github.io/quarto-r/news/index.html
• Report issues: https://github.com/quarto-dev/quarto-r/issues

For detailed examples and workflows, check out the new vignettes:

• Dynamic metadata
• Markdown in HTML tables
• Working with R scripts
• All vignettes

Acknowledgments

Special thanks to all contributors that helped make this release:

@asadow , @caiolivf , @caocloud , @cderv , @coatless , @ColinFay , @cwickham , @davidrsch , @DillonHammill , @eitsupi , @GeorgeBatten , @gordonwoodhull , @jennybc , @jeroen , @joanbadia , @JosephBARBIERDARNAL , @LiNk-NY , @llrs-roche , @milanmlft , @papayoun , @petermacp , @remlapmot , @salim-b , @saudiwin , @smzimbo-bayer , @srvanderplas , and @wjschne .

Happy Quarto-ing with R!

The Problem: Repetitive Reporting

Would you rather read a generic “Climate summary” or a “Climate summary for exactly where you live”? Reports that are personalized to a specific situation increase engagement and connection. But producing many customized reports manually is tedious and error-prone.

Quarto solves this with parameterized reports—you create a single document template, then render it multiple times with different parameter values to generate customized outputs automatically.

A great example is the customized soil health reports from Washington Soil Health Initiative’s State of the Soils Assessment , presented at posit::conf(2023) by Jadey Ryan (watch on YouTube ). Jadey demonstrated this approach using R and plain text Quarto files (.qmd).

This post shows you how to apply the same principles using Python: we’ll walk through converting a Jupyter notebook (.ipynb) into a parameterized report, then automating the generation of multiple customized outputs. Then I’ll give you some tips for making your reports look polished.

The Solution: Parameterized Reports

Start with a notebook

As an example, let’s start with a Jupyter notebook analyzing climate data for Corvallis, Oregon.

You can see the full notebook, corvallis.ipynb, on GitHub , but here are the key pieces:

• The code cells import some data for all of Oregon, and filter it to just rows relevant for Corvallis, then produce a summary sentence and a plot.

• The document options specify echo: false so no code appears in the final output, and format: typst so the output is a PDF produced via Typst , a modern alternative to LaTeX.

This single notebook can be rendered with Quarto:

1

quarto render corvallis.ipynb 

The result is a PDF file, corvallis.pdf, a simple report with the title “Corvallis” and a single sentence summary of the climate data, along with a plot highlighting the mean temperature for this year against the last 30 years.

Now, imagine we want to create this report for the 50 largest cities in Oregon. Here’s the steps we’ll take:

1. Turn hardcoded values into variables
2. Declare those variables parameters
3. Render the notebook with different parameter values
4. Automate rendering with many parameter values

1. Turn hardcoded values into variables

We want a report for each city. We’ll start by creating a variable, city, which we’ll designate a parameter in our next step. In a new code cell at the top of our notebook, we define the variable:

1

city = "Corvallis"

Then anywhere we previously hardcoded "Corvallis" in the notebook, we replace it with this variable.

The first occurrence is in the title of the document. Originally, we had a markdown cell defining a level 1 heading:

1

# Corvallis

We replace it with a code cell that uses an f-string to produce markdown for a level 1 heading based on the city variable:

1

Markdown(f"# {city}")

In the filtering step the replacement is straightforward, we just change the string to the variable:

1
2
3

tmean = tmean_oregon.filter(
    pl.col("city") == "Corvallis",
)

1
2
3

tmean = tmean_oregon.filter(
    pl.col("city") == city,
)

Finally, the plot code (using plotnine ), sets the title of the plot to include the city name:

1
2
3

...
+ labs(title = "Corvallis, OR", ...)
...

We can also use an f-string here to include the city variable:

1
2
3

...
+ labs(title = f"{city}, OR", ...)
...

Now, we should be able to test our changes by explicitly setting the city variable to something other than “Corvallis” and re-running the cells. Since our report is no longer specific to Corvallis, we can rename it climate.ipynb.

2. Declare those variables parameters

Now we have a variable that represents the parameter, we need to let Quarto know it’s a parameter. Quarto’s parameterized reports are implemented using Papermill , and inherit Papermill’s approach: tag the cell defining the parameter with parameters.

In Jupyter, you can add this tag through the cell toolbar:

You can see the updated notebook, now a parameterized notebook, on GitHub: climate.ipynb .

3. Render with different parameter values

If we render climate.ipynb, it will still produce the same report for Corvallis, because we haven’t changed the parameter value:

1

quarto render climate.ipynb

But we can now pass parameter values to Quarto with the -P flag:

1
2
3
4
5

# Generate report for Portland
quarto render climate.ipynb -P city:Portland --output-file portland.pdf

# Generate report for Eugene  
quarto render climate.ipynb -P city:Eugene --output-file eugene.pdf

We’ve also added --output-file to ensure each report gets its own filename.

4. Automate rendering with many parameter values

To generate all 50 reports, we need to run quarto render 50 times, each time with a different city as the parameter value. You could automate this in many ways, but let’s use a Python script. For example, you might have a dataset of cities and their corresponding output filenames:

1
2
3
4

cities = pl.DataFrame({
    "city": ["Portland", "Cottage Grove", "St. Helens", "Eugene"],
    "output_file": ["portland.pdf", "cottage_grove.pdf", "st_helens.pdf", "eugene.pdf"]
})

I’ve generated a small example above, but in reality you would likely read cities in from a file. Then you could iterate over the rows of this dataset, rendering the notebook for each city:

1
2
3
4
5
6
7

from quarto import render
for row in cities.iter_rows(named=True):
    render(
        "climate.ipynb",
        execute_params={"city": row["city"]},
        output_file=row["output_file"],
    )

Run this script once, and you’ll get all 50 custom reports!

You can find the complete working example on GitHub: cwickham/one-notebook-many-reports/03-many-reports .

Pretty Reports: Brand and Typst

The steps above to produce parameterized reports apply to any output format supported by Quarto. However, if you are targeting typst you can take advantage of additional features to create beautiful PDF reports.

Brand.yml

Quarto supports brand.yml a way to specify colors, fonts, and logos:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

color:
  palette:
    forest-green: "#2d5a3d"     
    charcoal-grey: "#555555"    
  foreground: charcoal-grey    
  primary: forest-green       
typography:
  fonts:
    - family: Open Sans
      source: google
  base:
    family: Open Sans
logo:
  medium: logo.png

Quarto will detect the _brand.yml file and apply the colors, fonts and logo to your report. Colors and fonts in your figures will need to be customized in your code, but that is made much easier with the brand-yml Python package which imports your values from _brand.yml.

You can see a full example of using _brand.yml with climate.ipynb at cwickham/one-notebook-many-reports/04-branded-reports , and learn more about Quarto’s support for brand in the Brand guide .

Typst

Learning a little bit of Typst syntax can take your reports from basic to beautiful. You can include raw Typst syntax in your notebooks, or wrap elements in Typst functions using the typst-function Quarto extension . As an example, you could add a header with the city name and a map of the location:

You can see the source for this example at cwickham/one-notebook-many-reports/05-pretty-reports .

jupyter vs knitr

The steps for creating a parameterized report above are specific to documents that use the jupyter engine. With a Jupyter notebook (.ipynb), or a plain text Quarto document (.qmd) with only Python code cells, Quarto will default to the jupyter engine. As described above, the jupyter engine uses cell tags to identify parameters.

If you are working in a .ipynb file, your IDE will likely provide a way to add these tags through the cell toolbar. If you are working in a .qmd file, you can add tags as a code cell option:

1
2
3
4

```{python}
#| tags: [parameters]
city = "Corvallis"
```

With the jupyter engine, parameters can then be accessed directly as variables, e.g. city, in later code cells.

If you are working in a Quarto document (.qmd) with R code cells, Quarto will default to the knitr engine. With the knitr engine, you set parameters in the document header under params:

1
2
3
4

---
params:
  city: "Corvallis"
---

In knitr, parameters are accessed as elements of params, e.g. params$city.

You can read more about setting and using parameters in Guide > Computations > Parameters .

Wrapping Up

Parameterized reports turn one notebook into many customized outputs. You’ve seen the process of going from a notebook with a hardcoded value to a parameterized report that can be rendered with different values. You can then automate the rendering in any way you choose to generate dozens of reports at once.

GitHub Codespaces is a cloud-powered, on-demand development environment that runs either in your browser or in Visual Studio Code via the GitHub Codespaces extension . It eliminates the need for lengthy local setup by providing a fully configured development container, complete with all necessary dependencies and tools. This means that whether you’re an instructor or a developer, you can start coding immediately with a consistent environment tailored to your specific project, right on your web browser.

More importantly, the participants of your workshops can use GitHub Codespaces just as easily as you can. With Codespaces, you and your participants all work on identical environments, minimising the “it doesn’t work on my machine” problems we are all too aware of.

In this post, I am assuming the case of a workshop instructor and a room full of participants with different laptops and operating systems. Codespaces are also useful for development, though, as you will notice reading on.

The Power of Combining Quarto CLI with Codespaces

Imagine a world where your participants are instantly equipped with the same environment with all the tools, libraries, and sample projects ready to go in the cloud. That’s the magic of using Codespaces:

1. Immediate Onboarding: Workshop participants or students can bypass the hassle of local setup. They simply launch a Codespace (running on their web browser of choice, independently of operating system), and the pre-configured environment is available immediately.

2. A Consistent Environment: Ensuring that everyone has the same tools and dependencies can be challenging. Codespaces lets you pre-define your environment with container configurations, reducing the risk of discrepancies in software versions or settings.

3. Reproducible Workflows: Whether you’re teaching a data science workshop or collaborating on a research paper, reproducibility is crucial. Because GitHub Codespaces uses the Dev Container specification , you can ensure that your code can be run in the same environment. When participants are ready to run their projects locally, they can use Codespace to build an equivalent Docker container.

GitHub provides “deep link” to Codespaces, allowing you to create a link you can share with your students or workshop participants.

For example, the quarto-codespaces repository provides several Dev Container / Codespaces configurations. The following link will create a new Codespace using the .devcontainer/universal/devcontainer.json configuration file instead of the default .devcontainer/devcontainer.json file.

1

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mcanouil/quarto-codespaces?quickstart=1&devcontainer_path=.devcontainer%2Funiversal%2Fdevcontainer.json)

The link can include a specific branch, a particular file, or even a specific line in a file, allowing you to guide participants directly to the relevant content and setup. By doing nothing more than clicking that one link, participants create or resume an existing execution environment.

Setting Up Your Own Quarto-Codespaces Environment

If you’re considering using Codespaces with Quarto CLI for your next workshop or teaching module, here’s how to get started:

Leverage the example provided by the quarto-codespaces repository or create your own Codespaces using the default .

Use an Existing Docker Image

The easiest way to get started is to use an existing Docker image that has Quarto CLI and all the dependencies you need. There are several pre-built images available with or without the Quarto CLI:

• Official Docker images:
  • ghcr.io/quarto-dev/quarto
  • ghcr.io/quarto-dev/quarto-full
• Community Docker images:
  • ghcr.io/mcanouil/quarto-codespaces
• Default Codespaces image:
  • mcr.microsoft.com/devcontainers/universal

You can use any of these images as a base for your Codespace. Inside the .devcontainer/devcontainer.json file, you can specify the image you want to use. The .devcontainer/devcontainer.json file serves as the blueprint for your Codespace.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "name": "My Workshop Setup",
  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
  "customizations": {
    "vscode": {
      "extensions": [
        "quarto.quarto",
        "mcanouil.quarto-wizard"
      ]
    },
    "codespaces": {
      "openFiles": [
        "exercises/intro-to-quarto.qmd",
        "exercises/computation.qmd"
      ]
    }
  }
}

Line 3

The Docker image is specified in the image field. It’s built using a Dev Container specification that you can find in .github/.devcontainer .

Line 8

The quarto extension for Visual Studio Code / Positron to provide support for Quarto documents.

Line 9

The quarto-wizard extension for Visual Studio Code / Positron to provide assistance in managing Quarto extensions

Line 13

The openFiles field specifies the files to open when the Codespace is created. This is useful for guiding participants to the right files or folders. See the Codespaces documentation for more information.

Configure the Development Container

You can fork the quarto-codespaces repository as a starting point for your own Codespaces. This repository includes the Dev Container configuration file (i.e., .devcontainer/devcontainer.json) that instruct Codespaces on how to set up an environment complete with Quarto CLI and other essential tools.

The .devcontainer/devcontainer.json configuration file ensures that every instance of your Codespace is identical, capturing everything from the Quarto CLI version to additional libraries or extensions you might need.

The quarto-codespaces repository is a great starting point as it provides a prebuilt Docker image with the latest Quarto CLI, Python, R, and Julia installed (i.e., ghcr.io/mcanouil/quarto-codespaces using .github/.devcontainer/devcontainer.json ).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

{
  "name": "Quarto",
  // "image": "buildpack-deps:jammy-curl",
  "build": {
    "dockerfile": "./Dockerfile",
    "context": ".",
    "args": {
      "VARIANT": "jammy"
    }
  },
  "remoteUser": "vscode",
  "features": {
    "./quarto-computing-dependencies": {
      "rDeps": "rmarkdown,languageserver,nx10/httpgd@v2.0.3,prompt,lintr",
      "pythonDeps": "jupyter,papermill",
      "juliaDeps": "IJulia"
    },
    "./uv": {
      "version": "latest"
    },
    "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {
      "version": "release",
      "installTinyTex": "true",
      "installChromium": "false"
    }
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "quarto.quarto",
        "mcanouil.quarto-wizard",
        "REditorSupport.r",
        "Posit.air-vscode"
      ],
      "settings": {
        "r.rterm.option": [
          "--no-save",
          "--no-restore-data",
          "--quiet"
        ],
        "[r]": {
          "editor.defaultFormatter": "Posit.air-vscode",
          "editor.formatOnSave": true
        }
      }
    }
  }
}

Line 3

The image field specifies the base image for the container. You can customise this to suit your needs.

Line 12

The features section allows you to add additional tools or libraries. See the Dev Container Features available for a comprehensive list of available features.

Line 13

The quarto-computing-dependencies feature is a “local” custom feature that installs the computing dependencies: R, Python, and Julia. This is a great way to ensure that your Codespace has everything it needs to run Quarto documents.

Line 18

The uv feature installs the uv tool to manage Python packages and project dependencies.

Line 21

The quarto-cli feature installs the Quarto CLI. You can specify the version you want to install, and it will be automatically downloaded and installed in your Codespace. You can see the code for this feature in the source repository: https://github.com/rocker-org/devcontainer-features/tree/main/src/quarto-cli .

Line 27

The customizations section allows you to specify settings and extensions for Visual Studio Code.

You can also add additional features to the devcontainer.json to suit your needs or start directly using the image as is as shown in Use an Existing Docker Image .

For example, you might want to add additional R packages or Python libraries. You can do this by using the quarto-computing-dependencies custom feature and changing the rDeps, pythonDeps, and juliaDeps fields to include the packages you want to install globally, or by using the postStartCommand field to run a script that installs the packages you need.

1
2
3
4
5
6

{
  "name": "My Workshop Setup",
  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
  "postStartCommand": "uv venv && source .venv/bin/activate && uv pip install -r requirements.txt"
}

You can also use the postStartCommand field to run a script that installs the packages you need.

1
2
3
4
5
6

{
  "name": "My Workshop Setup",
  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
  "postStartCommand": "bash ./init-env.sh --what all --force"
}

Line 5

The postStartCommand field specifies a command to run after the Codespace is started. In this case, it runs the init-env.sh script from quarto-codespaces repository with the --what all and --force options.

Benefits for Workshops and Teaching

When it comes to educational sessions, consistency and ease-of-use are paramount. Pairing Codespaces with Quarto CLI brings many direct benefits to a teaching environment:

• Streamlined Onboarding: Students and workshop attendees can get right to work without spending time installing and configuring local environments.
• Live, Interactive Sessions: Instructors can demonstrate live edits to Quarto documents. Changes can be rendered instantly and reflect in each participant’s environment: perfect for a hands-on, interactive learning experience.
• Collaboration and Version Control: All changes can be recorded in Git, making it easy to track progress, handle peer reviews, and manage collaborative projects, all within a single hosted environment.
• Elimination of “Dependency Hell”: With containerised development, all attendees work from the same baseline, ensuring that version conflicts or missing libraries don’t derail a session.

Final Thoughts and Future Directions

Whether you’re running a workshop, teaching a class, or collaborating on research, using Codespaces can reduce setup hassles, foster reproducibility, and encourage interactive learning.

In addition to the benefits mentioned above, other features further enhance your experience with Codespaces and Quarto CLI:

• Automated Pipelines: Integrating CI/CD tools to automatically validate Quarto document renders and catch errors using the exact same environment. See GitHub Actions: Running jobs in a container
• Real-Time Co-Editing Features: Enhancing collaborative sessions with simultaneous multi-user editing directly in Codespaces. See GitHub Codespaces: Real-time collaboration

This post covered the basics of using Codespaces and Quarto together, but there’s much more to Codespaces. Learn more by consulting their documentation .

Happy teaching!

Disclaimer

GitHub Codespaces is a product of GitHub, Inc. and comes with a quota of free usage, including CPU hours and storage. Be sure to check the GitHub Codespaces billing documentation and your current GitHub plan to avoid unexpected charges. If you are a student or an educator, you can explore the GitHub Education program and GitHub Classroom .

Acknowledgements

Thanks to Carlos Scheidegger , Julia Silge , and James J. Balamuta for their feedback and suggestions on this post.

We are especially enthusiastic about the improvements 1.7 brings to dark mode: you can now specify light and dark themes via brand, map computational outputs to themes, and have your website theme follow your viewer’s preference. To celebrate these changes, this site, quarto.org , now has a light and dark mode. Toggle the switch in the navigation bar () to see the difference.

You can read about these improvements and some other highlights below. You can find all the changes in this version in the Release Notes .

Dark Mode Improvements

Specify light and dark themes via brand.yml

You can now specify a light and dark brand. For example, at a project-level you can provide two brand files:

1
2
3

brand:
  light: light-brand.yml
  dark: dark-brand.yml

Standalone HTML pages, websites, and dashboards will gain a light switch toggle allowing viewers to switch between the light and dark themes.

By default Typst documents will use the light brand, but you can set the brand-mode option to use the dark brand instead:

1
2
3
4
5

---
format:
  typst:
    brand-mode: dark
---

Read about other ways to set a light and dark brand in Guide > Brand .

Map computational outputs to themes

A new code cell option, renderings, allows you to indicate which computational outputs should be displayed in light and dark mode. Create light and dark versions of your outputs in a single code cell, and add the option renderings to specify the order of the outputs. For example, this cell creates a light version of a plot, then a dark version:

1
2
3
4
5
6
7

```{r}
#| renderings: [light, dark]
plot(1:10) # Shown in `light` mode

par(bg = "#000000", fg = "#FFFFFF", col.axis = "#FFFFFF")
plot(1:10) # Shown in `dark` mode
```

Both outputs are produced, but you’ll only see the one corresponding to the current state of the light switch. Toggle the switch in the navigation bar to see the image change to reflect the theme.

Respect user color scheme

Set the new html format option respect-user-color-scheme to true if you would like your site to honor the viewer’s operating system or browser preference for light or dark mode:

1
2
3

format:
  html:
    respect-user-color-scheme: true

Other Highlights

• Typst updated to 0.13.0

• Pandoc updated to 3.6.3

• New version shortcode to insert the version of Quarto used to build your document:

  Rendered with Quarto 1.9.36

• Updated LaTeX and Beamer template partials:

  • LaTeX partials
  • Beamer partials

  These changes reflect the updates made in Pandoc 3.5 to separate the LaTeX and Beamer document templates and introduce some additional partials for both. If you have custom formats that provide custom templates or partials, you may need to update them to work with the new partials.

• Improvements to the julia engine:

  • juliaup integration : Use specific versions of Julia in your notebooks.

  • R and Python support : Include {r} and {python} executable code cells via the RCall and PythonCall packages.

  • Caching : Save time rendering long-running notebooks by caching results.

  • Revise.jl integration : Automatically update function definitions in Julia sessions.

Acknowledgements

We’d like to say a huge thank you to everyone who contributed to this release by opening issues and pull requests:

AndreasThinks , ArthurData , BrendonChau , DanStuder , DavidFirth , Eli-78-fas , EllaKaye , EmilHvitfeldt , EvoArt , FMKerckhof , FrankwaP , JanPalasek , Jocarnail , MHellmund , MichaelHatherly , Noghpu , PeneLoopy , Rafnuss , SergeCroise , TonyFly3000 , actuaristai , alex-r-bigelow , andrewheiss , ant-durrant , antoine4ucsd , arnaudgallou , aronatkins , arthurgailes , bkowshik , boshek , cbrnr , cl-roberts , cmadland , coatless , deepayan , devmcp , dhimmel , dkapitan , dmenne , eamcvey , edavidaja , fredguth , fuhrmanator , gadenbuie , github-actions[bot] , glin , gwbrck , hchulkim , hguturu , hturner , ihrke , jdutant , jenslaufer , jkrumbiegel , jmgirard , joelostblom , kandolfp , kapsner , kazuyanagimoto , kdheepak , kingo55 , knuesel , kubu4 , kv9898 , kylie-foster , loneguardian , lwjohnst86 , ma2048 , markjholmes , maurosilber , mipmip , mroavi , mroberts1 , msh855 , mvuorre , nathanj3 , odysseu , parmsam , peter-gy , pvelayudhan , raffaem , robmcd , ryanzomorrodi , stragu , sun123zxy , t-kalinowski , temospena , tjni , torven-schalk , turcotte , wenyaoliu , yhkee0404 .

Additional links:

• Quarto 1.6 release post
• Download Positron
• Quarto’s _brand.yml documentation

There may be times when you would like to single-source content across multiple pages/files to reduce the risk of errors, produce consistent content that is easy to maintain, and ultimately save valuable time. Quarto (an open-source technical publishing system), provides an Includes feature (the equivalent of an R Markdown “child” document) that allows you to reuse content across multiple documents/files/pages.

To achieve this, simply create chunks of content (text, tables, code, callouts, images, etc.) and then insert it using the Include shortcode: {{< include _content.qmd >}}.

Typically, you must keep your content general enough so it can be reused in several places. In other words, if you needed to add a name or an image that is specific to that file, you would assume that you wouldn’t be able to use an include, or you would have to use several smaller includes sewn into uniquely written content.

But what if you need your single-sourced content to be more specific? You can use Includes with meta shortcode (variables) to add precise values defined at the file level.

Walkthrough example

Let us walk you through an example of how to achieve this.

Before you begin:

• Quarto version 1.5+ was used for this walkthrough example.
• This has been tested with both new and existing Website projects.
• A var shortcode enables you to insert content from the project or file level.
• The meta shortcode allows you to insert content from Pandoc metadata (e.g., YAML at the top of the document and/or in _quarto.yml).
• As you preview your site, pages will be rendered and updated. However, if you make changes to global options (e.g. _quarto.yml or included files) you need to fully re-render your site to have all of the changes reflected. Consequently, you should always fully quarto render your site before deploying it, even if you have already previewed changes to some pages with the preview server.

Create the content:

Here is an example of a file with content we want to reuse across several pages.

1

In this document, we cover facts that are unique to the state, like the state's population, its flower, and animal.

This content is general enough to use as each state’s introduction but lacks the facts that are unique to each state. So, we could insert the Include into each state’s file and then add specific content that is unique to the state:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
title: New York
---

{{< include _snippets/state-intro.qmd >}}

New York has a geographical size of 54,555, making it the 27th largest state with an estimated population size of 19.8 million.

The state's flower is the Rose, as shown below:

![](images/ny/flower.png)

Why are we doing this?

Instead of copying and pasting this content into each file, and then updating it with each state’s fact (which introduces a higher risk of making an error), we can use meta variables to insert specific values.

Let’s execute

First, I create a file within my _snippets directory named facts.qmd. Throughout the file, I am going to insert a unique meta variable for each occurrence that I want the content to be specific to the state:

1

{{< meta state >}} covers approximately {{< meta square-miles >}} making it the {{< meta size-rank >}} largest state in the United States. As of 2023, {{< meta state >}} has an approximate population of about {{< meta population >}}.

I can define each of the meta variables within the individual file that I plan on reusing this content. So, in my ny.qmd file, I define each variable in the YAML metadata. Then, insert the facts.qmd file with the undefined meta shortcodes using an include:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
title: New York
state-abbr: ny
state: New York
size-rank: 27th
square-miles: 54,555
population: 19.8 million
---


{{< include _snippets/facts.qmd >}}

As you can see, the rendered file has the meta shortcodes populated with the definitions that you assigned to each value in the file’s YAML.

But, I would also like to add the state’s flower and animal with images of each. You can achieve this by editing the document to add this information and images:

1
2
3
4
5
6
7
8
9

{{< include _snippets/facts.qmd >}}

New York's official flower is the Rose:

![](../images/ny/flower.png)

And the official animal is the Beaver:

![](../images/ny/animal.png)

Or, you can get creative and use meta shortcodes in your image paths so you can continue to manage all of the content in a single file:

1
2
3
4
5
6
7

{{< meta state >}}'s official flower is the {{< meta flower >}}, pictured below:

![The official {{< meta state >}} state flower, the {{< meta flower >}}](../images/{{< meta state-abbr >}}/flower.png)

Lastly, {{< meta state >}}'s official animal is the {{< meta animal >}}, pictured below:

![The official {{< meta state >}} state animal, the {{< meta animal >}}](../images/{{< meta state-abbr >}}/animal.png)

As you can see, my image paths have {{< meta state-abbr >}} which is defined in the new-york file as “ny”.

When we render the project, the image path updates to /images/ny/flower.png pointing to the existing flower image in the ny directory:

In theory, you could do this for each state as long as each directory follows the same naming conventions, i.e., pa/flower.png and vt/flower.png.

This does require an organized and scalable approach since the images will have to follow the same directory and file-naming conventions, but in doing so, you can create individualized pages and images using a single include.

The rendered example

Here is New York’s page:

Here is Pennsylvania’s page:

Each page was built using a single (shared) file:

1

{{< include _snippets/facts.qmd >}}

Learn more about Quarto Includes

Quarto’s Includes feature allows you to improve your content creation process by reducing redundancy and maintaining consistency across multiple documents. Whether you’re managing technical documentation, educational materials, or any other content, this approach can help you save time, reduce errors, and deliver polished results.

Learn more with these resources:

• Get Started - Quarto
• Quarto - Includes
• Quarto - meta Variables
• An overview of Single Source Authoring

YouTube Playlist

Quarto Websites 1: Build your homepage

In this video, you’ll get a running start by using a template we’ve designed to be functional and attractive, and that will serve as a foundation for the rest of the video series. You’ll customize the content of your homepage, and how it looks, and along the way learn about the two key files in a Quarto website index.qmd and _quarto.yml. Finally, you’ll learn one way to publish your website so other people can see it.

Links: About pages | YAML appearance options

Code: Starter | Final

Quarto Websites 2: Add pages and navigation

Now you’ve got a homepage, you’ll likely want to add some other pages. In this video, learn how to add pages to your website, and help people find them, by adding them to your website navigation.

Links: Bootstrap icons | Navigation bar options | Quarto website navigation

Code: Starter | Final

Quarto Websites 3: Customize appearance with CSS/SCSS

You now have a set of content you are happy with on your website, but how do you customize the look and feel of your site beyond options set in YAML? In this video, you’ll start by learning the basics of CSS and SCSS and how to make good design choices. Then, you’ll see how to apply these choices to your Quarto website.

Links: Color contrast checker | Google fonts

Code: Starter | Final

Quarto Websites 4: Add lists of content with listings

Adding a listing page to your website is a great way to showcase your projects, talks, publications or blog posts. In this video you’ll learn how to create a listing page in Quarto and see two ways to populate it with content: Quarto documents, or a yaml file.

Links: Listings | Andrew Heiss’ teaching listing

Code: Starter | Final

We are particularly excited about:

• Support for brand.yml—a single file that defines your organization’s branding and style preferences across formats.

• RevealJS updates, including the new navigation features: scroll mode and jump to slide.

• The contents shortcode for reordering your content.

• landscape blocks for placing content on a landscape page.

• Improvements in how you can specify subpanels of cross-references from code blocks.

You can read about these new features and a couple of breaking changes in the sections below. You can find all the changes in this version in the Release Notes .

Cross-format theming with brand.yml

brand.yml is a Posit project outside Quarto that defines brand information using a simple YAML file. Quarto is a flagship adopter of brand.yml and supports brand-themed output for html, dashboard, typst and revealjs formats.

As an example, consider the following _brand.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

color:
  palette:
    dark-grey: "#222222"
    blue: "#ddeaf1"
  background: blue
  foreground: dark-grey
  primary: black

logo: 
  medium: logo.png

typography:
  fonts:
    - family: Jura
      source: google
  base: Jura
  headings: Jura

When this _brand.yml is placed in a project, webpages, presentations, PDF reports, and dashboards will share a common appearance:

View the example: Source | Live website

Get started by reading the Quarto Guide to Brand .

RevealJS update

Quarto v1.6 updates RevealJS to v5.1.0. With the update comes two notable features:

Jump to Slide : Quickly navigate to a slide. Press G to activate, type a slide number or ID, and hit Enter/Return.

Scroll Mode : Scroll rather than click to advance slides. Press R, add ?view=scroll to your URL, or use the Navigation menu to activate. Automatically activated on small screens.

Contents shortcode

The contents shortcode lets you compose content in one location in your document and then display it in another. For example, you might use a code cell to generate a plot:

1
2
3
4
5
6

```{python}
#| echo: false
#| label: a-cell
import matplotlib.pyplot as plt
plt.plot([1,2,3])
```

Then use the contents shortcode to display that plot in a callout by referencing its label, a-cell:

1
2
3
4
5
6

::: callout-note
## Note the following plot

{{< contents a-cell >}}

:::

Find all the details on our guide page on the contents shortcode .

Landscape mode

In pdf, docx, and typst formats, you can now put content on a landscape page by placing it inside a landscape block :

1
2
3
4
5

::: {.landscape}

This will appear in landscape.

:::

Cross-reference improvements

It should now be easier to get Quarto to recognize subfloats (subtables, subfigures, etc) when they’re emitted by code cells. If the subcap attribute of a code cell has as many entries as the number of outputs from your code cell, Quarto knows to accept those as subfloats. See #10328 for details.

Minimal example:

1
2
3
4
5
6
7
8
9

```{{r}}
#| label: tbl-example
#| tbl-cap: I want these images to be interpreted as Tables.
#| tbl-subcap:
#|   - This is the subcaption for the first subtable
#|   - This is the subcaption for the second subtable
plot(1:10)
plot(11:20)
```

Breaking Changes

We try very hard to keep Quarto backward compatible. However, in this release, there are a couple of breaking changes due to upstream dependencies. You may be affected if:

• You have TypeScript files (*.ts) that you use either with pre- or post-render scripts, or with quarto run, that import Deno standard libraries.

  The import syntax has changed. Please see Deno Scripts for the necessary changes.

• You override the LaTeX graphics.tex partial, or you have a completely custom LaTeX template that doesn’t use the graphics.tex partial.

  A Pandoc change means some images are now wrapped in \pandocbounded. Consequently, your graphics.tex partial, or your template, needs to define \pandocbounded. You can look at our source code for graphics.tex to see the necessary changes and read more about the upstream change in Pandoc commit 26b25a4.

Acknowledgments

We want to say a huge thank you to everyone who contributed to this release by opening issues and pull requests:

ArthurData , Blake-Madden , Coding4Sec , EricMarcon , Fgazzelloni , GeorgRamer , Gewerd-Strauss , GuillaumeDehaene , HarunCelikOtto , IULibScholComm , IndrajeetPatil , LeoLuongVuong , MarcellGranat , Mavoort , Nenuial , PeteArm , ShixiangWang , Steinthal , Walser52 , Xinenomine , abbyruthe , aborruso , adamblake , albert-ying , alecloudenback , allefeld , aronatkins , arthur-shaw , astrowonk , avras , baker-jr-john , bcm0 , blackerby , boshek , brandonmontez , brianmsm , bryanhanson , carschandler , castedo , chaz-clark , christopherkenny , coatless , d-morrison , danieltomasz , daxkellie , ddlawton , debruine , dsbitor , e-miz , eculler , edavidaja , edvinsyk , eitsupi , ethanwhite , fermarsan , floesche , fradav , fredguth , gadenbuie , georgestagg , github-actions[bot] , halleysfifthinc , hamelsmu , hansfn , harrylojames , hodgesmr , holtzy , hugetim , hurak , iagopinal , isabelizimm , itsmevictor , jameslairdsmith , javajon , jchiquet , jdfoote , jido , jimjam-slam , jkrumbiegel , jmgirard , jmhammond , joelostblom , johannes-menzel , juliantao , jvcarli , kazuyanagimoto , kbvernon , kdheepak , kjohnsen , lballabio , leovan , loneguardian , longapalooza , lucacasonato , lukmanaj , lwjohnst86 , machow , maelle , masud90 , melaniewalsh , mfisher87 , mipmip , mitzimorris , mpr1255 , nessan , neuwirthe , nichtich , njericha , nsarang , olivroy , ozanozbeker , paciorek , pagiraud , parmsam , pedrohbraga , peteole , produnis , raffaem , ryarazi , ryjohnson09 , s2t2 , salim-b , samlalwani , sgelzenleuchter , skriptum , snhansen , stragu , sun123zxy , sverrirarnors , topepo , truecluster , tylere , winniehell , xtimbeau , yogabonito , yurivict , yves-amevoin .

The palette emoji in the listing and social card image for this post comes from OpenMoji– the open-source emoji and icon project. License: CC BY-SA 4.0

Materials: YouTube playlist | Slides | Starter code

1. Hello, Quarto Dashboards

Start by getting to know Quarto dashboards and make your very first dashboard using either R or Python and share it online. Slides

2. Quarto Dashboards Components

Then, build up your arsenal of dashboard components to add navigation, sidebars, tabsets, value boxes, and fine-tune layout. Slides

3. Quarto Dashboards Theming and Styling

Finally, make your dashboard pop by adding a theme and making styling tweaks. Slides

Talks included in this playlist are as follows:

• Updates from Posit, with Hadley Wickham, Charlotte Wickham, George Stagg, and James Blair
• Andrew Bray - Closeread: bringing Scrollytelling to Quarto
• Meghan Hall - Designing and Deploying Internal Quarto Templates
• David Keyes - Report Design in R: Small Tweaks that Make a Big Difference
• Mine Çetinkaya-Rundel - Reproducible, dynamic, and elegant books with Quarto
• Cynthia Huang - Quarto for Knowledge Management
• Regina Lionheart - Making Waves with R, Python, and Quarto
• Joshua Cook - Quarto: A Multifaceted Publishing Powerhouse for Medical Researchers
• Tyler Morgan-Wall - Quarto, AI, and the Art of Getting Your Life Back
• Sean Nguyen - Beyond Dashboards: Dynamic Data Storytelling with Python, R, and Quarto Emails
• Richie Moluno - JSquarto: Bridging JavaScript Documentation with Quarto’s Power
• Mika Braginsky - DataPages for interactive data sharing using Quarto
• Brennan Antone - Democratizing Organizational Surveys with Quarto and Shiny