Last modified: 2026-10-11 02:07:28 (PDT)
Quarto is an open-source scientific and technical publishing system that allows you to create documents, books, websites, presentations, and more. Quarto provides a unified authoring framework for data science, combining your code, its results, and your prose. Quarto documents are fully reproducible and support dozens of output formats, like PDFs, Word files, presentations, and more.
Quarto files are designed to be used in three ways:
For communicating to decision-makers, who want to focus on the conclusions, not the code behind the analysis.
For collaborating with other data scientists (including future you!), who are interested in both your conclusions, and how you reached them (i.e., the code).
As an environment in which to do data science, as a modern-day lab notebook where you can capture not only what you did, but also what you were thinking.
Multi-format Output: Quarto documents can be rendered into HTML, PDF, MS Word, ePub, PowerPoint, Revealjs presentations, dashboards, websites, and books from a single source file. This allows authors to maintain one document but publish it in multiple formats without rewriting content.
Rich Markdown Authoring: Content is created in markdown, with support for figures, tables, equations (LaTeX), citations, cross-references, and advanced layout features like tabs, callouts, and panels.
Embedded Executable Code: Integrate code chunks (R, Python, Julia, Observable JS) that can be executed and the results rendered directly in the document. This allows for dynamic results, data analysis, plots, and reproducible research workflows.
Interactivity: Add interactive components such as widgets, tab sets, and collapsible sections for richer communication with readers.
Customization: Extensive theming and styling options, including custom CSS and advanced layout controls for polished, publication-quality output.
Project Management: Organize large projects and integrate with version control tools like Git. Use Quarto projects to group related documents, manage dependencies, and orchestrate rendering.
If you’re an R Markdown user, you might be thinking “Quarto sounds a lot like R Markdown.” You’re not wrong! Quarto unifies the functionality of many packages from the R Markdown ecosystem (rmarkdown, bookdown, distill, xaringan, etc.) into a single consistent system as well as extends it with native support for multiple programming languages like Python and Julia in addition to R. In a way, Quarto reflects everything that was learned from expanding and supporting the R Markdown ecosystem over a decade.
To get started with Quarto:
Installation: Quarto CLI is included with RStudio, so if you have a recent version of RStudio, you already have Quarto. Otherwise, visit https://quarto.org/docs/get-started/
Documentation: The official Quarto documentation is available at https://quarto.org/docs/guide/
R4DS Chapter: For an excellent introduction to using Quarto with R, see the Quarto chapter in R for Data Science (Wickham et al. 2023)
A Quarto document is a plain text file with the extension .qmd. It contains three important types of content:
---s```# heading and _italics_In RStudio, create a new Quarto document using File > New File > Quarto Document… in the menu bar. RStudio will launch a wizard that you can use to pre-populate your file with useful content that reminds you how the key features of Quarto work.
RStudio provides two ways to edit Quarto documents:
Visual Editor: The Visual editor provides a WYSIWYM interface for authoring Quarto documents. If you’re new to computational documents but have experience using tools like Google Docs or MS Word, the visual editor is the easiest way to get started. In the visual editor you can use the buttons on the menu bar to insert images, tables, cross-references, etc., or you can use the catch-all ⌘ + / or Ctrl + / shortcut to insert just about anything.
Source Editor: The source editor allows you to edit the raw markdown and code. While the visual editor will feel familiar to those with experience in word processors, the source editor will feel familiar to those with experience writing R scripts or R Markdown documents. The source editor can also be useful for debugging any Quarto syntax errors since it’s often easier to catch these in plain text.
You can switch between the visual and source editors at any time using the toggle in the top-left of the editor pane.
To produce a complete report containing all text, code, and results:
quarto::quarto_render("document.qmd") in R, orquarto render document.qmd in the terminalWhen you render the document, Quarto sends the .qmd file to knitr, which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output. The markdown file generated by knitr is then processed by pandoc, which is responsible for creating the finished file in your chosen format (HTML, PDF, Word, etc.).
To run code inside a Quarto document, you need to insert a chunk. There are three ways to do so:
```{r} and ```Chunks can be given an optional label and various chunk options:
Common chunk options include:
#| label: - give the chunk a name#| echo: false - hide the code but show the output#| code-fold: true - allow readers to toggle code visibility (useful when output is more important to the narrative than the code)#| eval: false - show the code but don’t run it#| include: false - run the code but hide both code and output#| warning: false - hide warnings#| message: false - hide messagesUse code-fold: true for chunks where the output is important to the narrative and not the code used to produce it. This allows interested readers to expand and view the code while keeping the document focused on results.
When rendering to multiple output formats (HTML, PDF, DOCX, EPUB), you may want different chunk options or behavior for different formats. Use knitr::pandoc_to() with if () statements to detect the output format and set format-specific settings.
Example: Different figure sizes for different formats
Example: Conditional code execution based on format
Common format detection patterns:
knitr::pandoc_to("html") - returns TRUE for HTML outputknitr::pandoc_to("latex") - returns TRUE for PDF outputknitr::pandoc_to("docx") - returns TRUE for Word outputknitr::pandoc_to("epub") - returns TRUE for EPUB outputThis technique is particularly useful when you need to:
Quarto uses Pandoc’s markdown for text formatting:
*italic* or _italic_ produces italic text**bold** or __bold__ produces bold text`code` produces code formatting# Heading 1, ## Heading 2, ### Heading 3 for headings- or *1., 2., etc.[link text](url) creates hyperlinks inserts imagesImportant: Always include a blank line before bullet lists and numbered lists in markdown and Quarto documents.
For more details on using Quarto for writing and analysis, see the Quarto chapter in R for Data Science (Wickham et al. 2023).
Quarto books let you author entire books (or course notes, manuals, dissertations, etc.) in markdown. Quarto books are ideal for documentation, tutorials, lab manuals, and other long-form content.
Starting from a template (recommended):
Using a template is the fastest way to get started with a Quarto book, as it provides pre-configured settings, example content, and GitHub Actions workflows for automated deployment:
qbt) - our recommended template, with pre-configured settings and CI:
While these templates jumpstart your project with up-to-date configuration and workflow files, you should still come up to speed on what all the config files do (particularly _quarto.yml and any GitHub Actions workflows) so you can modify and debug them as needed. The templates serve as central locations for the most current versions of these files and best practices.
Starting from scratch:
If you prefer to start from scratch, you can create a new Quarto book project using the Quarto CLI:
This will create a basic book structure with:
_quarto.yml - configuration file for your bookindex.qmd - the home page / prefacereferences.qmd - bibliography/references pageOnce you have a Quarto book project, you can build and preview it:
The quarto preview command starts a local web server and automatically refreshes the preview whenever you save changes to your files.
A typical Quarto book is organized as follows:
_quarto.yml: The main configuration file that defines:
Chapter files: Individual .qmd files for each chapter. These are listed in the chapters section of _quarto.yml.
Parts: You can organize chapters into parts for better structure:
Quarto books support many advanced features:
Cross-references: Reference figures, tables, equations, and sections throughout your book:
Citations: Include a bibliography and cite sources:
Search: Automatic full-text search in HTML output.
Downloads: Offer PDF, ePub, and Word versions alongside HTML.
Navigation: Automatic table of contents, previous/next chapter buttons, and breadcrumbs.
Customization: Custom themes, CSS, and templates for professional appearance.
The UCD-SERG lab manual is a Quarto book. You can view its source code at https://github.com/UCD-SERG/lab-manual to see how it structures chapters, used includes for modular content, and configured various output formats.
Quarto dashboards turn a .qmd (or Jupyter notebook) into a data dashboard by setting format: dashboard in the document YAML.
Layout is driven by ordinary markdown headings, which define pages, rows, columns, and tabsets; each computational cell becomes a “card” holding a plot, table, or text. Value boxes highlight key metrics, and sidebars and toolbars hold interactive inputs.
Dashboards work with R, Python, Julia, and Observable JavaScript, and display both interactive widgets ({plotly}, {leaflet}, {htmlwidgets}) and static graphics ({ggplot2}, Matplotlib).
By default a dashboard renders to static HTML, so it can be published anywhere a web page can (including GitHub Pages, like the rest of our Quarto output) with no server behind it. When server-side interactivity is genuinely needed, a Shiny backend can drive the dashboard, at the cost of needing a Shiny server to host it. For most lab reporting, start with the static form and add Shiny only if filtering or recomputation on the reader’s side becomes necessary.
See the dashboard examples gallery for layouts to copy from.
Quarto profiles allow you to customize rendering behavior for different purposes. A profile is a named set of configuration options that can be activated when rendering. This is particularly useful when you want to render the same source files in different formats or for different audiences.
Profiles let you maintain multiple _quarto.yml configuration files in the same project. For example, you might have:
_quarto.yml - default book configuration_quarto-revealjs.yml - configuration for rendering chapters as slide decks_quarto-print.yml - configuration optimized for PDF printingA excellent example of using Quarto profiles comes from the Regression Models for Epidemiology course materials by D. Morrison.
The project includes a _quarto-revealjs.yml profile that allows each chapter to be compiled as a RevealJS slide deck, in addition to being part of the book.
To render a single chapter as slides:
To render all chapters listed in the profile as slides:
To create a profile:
_quarto-{profile-name}.yml_quarto.yml--profile={profile-name}Example profile structure:
_quarto-slides.yml:
Multiple output formats: Maintain separate configurations for web, print, and presentation versions of your content.
Different audiences: Create versions with or without solutions, technical details, or instructor notes.
Development vs. production: Use a development profile with faster rendering options during writing, and a production profile with full features for final output.
Course materials: Render the same content as both a reference book and lecture slides, as demonstrated in the RME course.
Quarto provides a powerful cross-reference system for figures, tables, equations, and sections. Cross-references automatically number your content and create clickable links in HTML and PDF output.
Required label prefixes:
#fig- (e.g., #fig-workflow-diagram)#tbl- (e.g., #tbl-summary-stats)#eq- (e.g., #eq-regression-model)#sec- (e.g., #sec-introduction)#thm-, Lemmas: #lem-, Corollaries: #cor-#prp-, Examples: #exm-, Exercises: #exr-For figures (static images):
For code-generated figures:
For tables (markdown tables):
For code-generated tables:
Referencing in text:
@fig-label produces “Figure X”@tbl-label produces “Table X”@eq-label produces “Equation X”@sec-label produces “Section X”Benefits:
For complete details, see the Quarto Cross-References documentation.
Quarto’s include feature allows you to decompose large documents into smaller, more manageable files. This is particularly useful for books and long documents.
Basic syntax:
Benefits:
Better Git History: When sections are reordered, only the main chapter file changes (moving include statements), making it immediately clear that content was reorganized rather than edited.
Easier Code Review: Reviewers can see exactly what changed—either the organization (main file) or the content (include file).
Modular Maintenance: Each section lives in its own file, making it easier to find and edit specific content, reuse sections across chapters, and work on different sections simultaneously without merge conflicts.
Clear Structure: The main chapter file becomes a table of contents showing the organization at a glance.
Recommended pattern:
Main chapter file (e.g., 05-coding-practices.qmd):
Include files (e.g., coding-practices/section-name.qmd):
Note: The heading must be in the main file, followed by a blank line, then the include statement. This keeps the document structure clear in the main file.
For more details, see the Quarto Includes documentation.
When embedding raw source code from external files without executing them, the include-code-files extension provides a filter to include code directly into fenced code blocks with syntax highlighting and line or snippet selection.
Installation:
Add the filter to your document or _quarto.yml:
Usage:
Key capabilities:
start-line=10 end-line=25)snippet="main")Mermaid diagrams are a powerful tool for creating flowcharts, sequence diagrams, state diagrams, and other visualizations directly in your Quarto documents using text-based syntax. While mermaid diagrams work well in HTML output, they have significant limitations when rendering to DOCX (Word) and PDF formats as of early 2026.
Mermaid diagrams are created using fenced code blocks with the mermaid language tag:
This creates a simple flowchart that renders beautifully in HTML output.
As of early 2026, rendering mermaid diagrams to DOCX or PDF formats in Quarto is unreliable and problematic. These issues are well-documented in the Quarto community and stem from the underlying tooling used to convert diagrams to images.
When rendering documents with mermaid diagrams to DOCX format, you may experience:
These issues occur because Quarto relies on headless browser engines (Chrome or Edge via Puppeteer) to convert mermaid diagrams to images for inclusion in DOCX and PDF outputs. The browser integration can fail or hang, particularly when running in automated environments or when multiple diagrams are present.
Even when rendering succeeds, mermaid diagrams in DOCX and PDF output often suffer from:
Given these limitations, we recommend the following approaches when you need DOCX or PDF output:
The most robust workflow is to:
Example:
This approach guarantees compatibility with all output formats and gives you full control over image quality.
Use Quarto’s conditional content features to show different content based on output format:
This shows the live mermaid diagram in HTML output and a static image in DOCX/PDF outputs.
If you want to attempt rendering mermaid diagrams to DOCX, ensure you have Chrome or Edge installed. You can install Chromium via Quarto:
However, this does not guarantee successful rendering and may still result in hangs or failures.
When creating documentation that includes mermaid diagrams, prefer HTML as your primary output format. HTML rendering of mermaid diagrams is fast, reliable, and produces high-quality interactive diagrams.
If DOCX output is required for collaboration or submission, use one of the workarounds above.
In UCD-SERG/rpt PR #70, our team removed mermaid diagrams from package vignettes specifically because they were incompatible with DOCX output. This demonstrates the practical impact of these limitations in production workflows.
The Quarto development team is aware of these issues and working to improve diagram rendering support. Monitor the following resources for updates:
Check for improvements in newer Quarto versions, but as of early 2026, manual export and embedding remains the most reliable approach for DOCX and PDF outputs.
Key Takeaways:
When encountering issues with Quarto, the official Quarto Troubleshooting Guide provides comprehensive diagnostic tools and strategies. This section summarizes key troubleshooting approaches.
Use quarto check to verify your installation and dependencies:
This command checks for:
See the quarto check output and the official guide for the complete, authoritative list of checks.
Enable verbose logging to see detailed rendering information.
On Unix-like systems (macOS, Linux):
On Windows PowerShell:
Or pass at command line (all platforms):
Get stack traces for better error messages.
On Unix-like systems (macOS, Linux):
On Windows PowerShell:
Inspect log files for diagnostic information. Log file locations:
%LOCALAPPDATA%\quarto\logs~/Library/Application Support/quarto/logs~/.local/share/quarto/logs (or ${XDG_DATA_HOME}/quarto/logs if ${XDG_DATA_HOME} is set)Out-of-memory errors: When building large projects, increase memory allocation (example sets 8GB limit).
On Unix-like systems (macOS, Linux):
On Windows PowerShell:
PDF rendering issues: If you encounter PDF rendering problems, ensure you have an up-to-date LaTeX installation, or install Quarto’s TinyTeX:
Environment conflicts: If Quarto finds the wrong R or Python installation, use quarto check output to verify which installation Quarto is using. For R, you can render a diagnostic document with sessionInfo() to compare Quarto’s environment with your interactive R session.
For more specialized issues, consult the official Quarto Troubleshooting Guide, which covers:
When seeking help on the Quarto issue tracker, include diagnostic information from quarto check and relevant log files.
{litedown}, a lightweight R Markdown implementation aimed at simplicity and speedqbt) - our recommended book templateqwt) - our recommended website template, with slide, PDF, and Word output for each pageinclude-code-files - Quarto filter extension to include external code files directly inside fenced code blocks with syntax highlighting and line slicingThe Quarto development team uses GitHub “epics” to track collections of related bugs and planned improvements. These are useful for staying informed about known limitations and upcoming features:
For additional context about using Quarto: