--- name: quarto-authoring description: Use when the user is explicitly working with Quarto, .qmd files, _quarto.yml, Quarto projects, or Quarto features such as callouts, cross-references, citations, Mermaid diagrams, extensions, websites, books, presentations, and reports. Also use for explicit migration from or comparison with R Markdown, bookdown, blogdown, xaringan, distill, or Jupyter notebooks to Quarto. Do not use for general R Markdown or related-format questions unless Quarto or migration to Quarto is explicitly mentioned. metadata: author: Mickaël Canouil (@mcanouil) version: "1.4" license: MIT --- # Quarto Authoring > This skill is based on Quarto CLI v1.9.36 (2026-03-24). ## When to Use What Task: Write a new Quarto document Use: Follow "QMD Essentials" below, then see specific reference files Task: Add cross-references Use: [references/cross-references.md](references/cross-references.md) Task: Configure code cells Use: [references/code-cells.md](references/code-cells.md) Task: Add figures with captions Use: [references/figures.md](references/figures.md) Task: Create tables Use: [references/tables.md](references/tables.md) Task: Add citations and bibliography Use: [references/citations.md](references/citations.md) Task: Add callout blocks Use: [references/callouts.md](references/callouts.md) Task: Add diagrams (Mermaid, Graphviz) Use: [references/diagrams.md](references/diagrams.md) Task: Control page layout Use: [references/layout.md](references/layout.md) Task: Use shortcodes Use: [references/shortcodes.md](references/shortcodes.md) Task: Add conditional content Use: [references/conditional-content.md](references/conditional-content.md) Task: Use divs and spans Use: [references/divs-and-spans.md](references/divs-and-spans.md) Task: Configure YAML front matter Use: [references/yaml-front-matter.md](references/yaml-front-matter.md) Task: Find and use extensions Use: [references/extensions.md](references/extensions.md) Task: Apply markdown linting rules Use: [references/markdown-linting.md](references/markdown-linting.md) Task: Choose or configure a compute engine (knitr, jupyter, julia) Use: [references/engines.md](references/engines.md) ### Migration (only when converting an existing project) Do NOT read these references when writing new Quarto documents. Only read the one matching the source format when the user explicitly asks to convert or migrate an existing project. - R Markdown (.Rmd) to Quarto: [references/conversion-rmarkdown.md](references/conversion-rmarkdown.md) - bookdown project: [references/conversion-bookdown.md](references/conversion-bookdown.md) - xaringan slides: [references/conversion-xaringan.md](references/conversion-xaringan.md) - distill article: [references/conversion-distill.md](references/conversion-distill.md) - blogdown site: [references/conversion-blogdown.md](references/conversion-blogdown.md) - Jupyter notebook (.ipynb) to/from Quarto: [references/conversion-jupyter.md](references/conversion-jupyter.md) ## QMD Essentials ### Basic Document Structure ```markdown --- title: "Document Title" author: "Author Name" date: today format: html --- Content goes here. ``` A Quarto document consists of two main parts: 1. **YAML Front Matter**: Metadata and configuration at the top, enclosed by `---`. 2. **Markdown Content**: Main body using standard markdown syntax. ### Divs and Spans Divs use fenced syntax with three colons: ```markdown ::: {.class-name} Content inside the div. ::: ``` Spans use bracketed syntax: ```markdown This is [important text]{.highlight}. ``` Details: [references/divs-and-spans.md](references/divs-and-spans.md) ### Code Cell Options Syntax A code cell starts with triple backticks and a language identifier between curly braces. Code cells are code blocks that can be executed to produce output. Quarto uses the language's comment symbol + `|` for cell options. Options use **dashes, not dots** (e.g., `fig-cap` not `fig.cap`). - R, Python, Julia: `#|` - Mermaid: `%%|` - Graphviz/DOT: `//|` ````markdown ```{language} #| label: fig-example #| echo: false #| fig-cap: "A scatter plot example." # code that produces a figure ``` ```` Set document-level defaults in YAML front matter: ```yaml execute: echo: false warning: false ``` **Caching — critical engine difference:** Only suggest `#| cache: true` for R code cells (knitr engine). Never suggest it for other language cells — it does not work and will be silently ignored. The only correct approach is `execute: cache: true` in the top-level YAML front matter when using engines other than `knitr`. Python/Jupyter requires `jupyter-cache` (`pip install jupyter-cache`): ```yaml execute: cache: true ``` Details: [references/code-cells.md](references/code-cells.md) ### Cross-References Labels must start with a type prefix. Reference with `@`: - Figure: `fig-` prefix, e.g., `#| label: fig-plot` → `@fig-plot` - Table: `tbl-` prefix, e.g., `#| label: tbl-data` → `@tbl-data` - Section: `sec-` prefix, e.g., `{#sec-intro}` → `@sec-intro` - Equation: `eq-` prefix, e.g., `{#eq-model}` → `@eq-model` ````markdown ```{language} #| label: fig-plot #| fig-cap: "A caption for the plot." # code that produces a figure ``` See @fig-plot for the results. ```` Details: [references/cross-references.md](references/cross-references.md) ### Callout Blocks Five types: `note`, `warning`, `important`, `tip`, `caution`. ```markdown ::: {.callout-note} This is a note callout. ::: ::: {.callout-warning} ## Custom Title This is a warning with a custom title. ::: ``` Details: [references/callouts.md](references/callouts.md) ### Figures ```markdown ![Caption text](image.png){#fig-name fig-alt="Alt text"} ``` Subfigures: ```markdown ::: {#fig-group layout-ncol=2} ![Sub caption 1](image1.png){#fig-sub1} ![Sub caption 2](image2.png){#fig-sub2} Main caption for the group. ::: ``` Details: [references/figures.md](references/figures.md) ### Tables ```markdown ::: {#tbl-example} | Column 1 | Column 2 | | -------- | -------- | | Data 1 | Data 2 | Table caption. ::: ``` Details: [references/tables.md](references/tables.md) ### Citations ```markdown According to @smith2020, the results show... Multiple citations [@smith2020; @jones2021]. ``` Configure in YAML: ```yaml bibliography: references.bib csl: apa.csl ``` Details: [references/citations.md](references/citations.md) ## Common Workflows ### Creating an HTML Document ```yaml title: "My Report" author: "Your Name" date: today format: html: toc: true code-fold: true theme: cosmo ``` ### Creating a PDF Document ```yaml title: "My Report" format: pdf: documentclass: article papersize: a4 ``` ### Creating a RevealJS Presentation ```markdown --- title: "My Presentation" format: revealjs --- ## First Slide Content here. ## Second Slide More content. ``` ### Setting Up a Quarto Project Create `_quarto.yml` in the project root: ```yaml project: type: website website: title: "My Site" navbar: left: - href: index.qmd text: Home - href: about.qmd text: About format: html: theme: cosmo ``` ## Resources - [Quarto Documentation](https://quarto.org/docs/) - [Quarto Guide](https://quarto.org/docs/guide/) - [Quarto Extensions](https://quarto.org/docs/extensions/) - [Community Extensions List](https://m.canouil.dev/quarto-extensions/) --- Source attribution: posit-dev Original project: https://github.com/posit-dev/skills/blob/4400f97e73807dd0ead3f20cc2ad3ab3e10f568f/quarto/quarto-authoring/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Posit PBC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: posit-dev Original project: https://github.com/posit-dev/skills/blob/4400f97e73807dd0ead3f20cc2ad3ab3e10f568f/quarto/quarto-authoring/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Design, Marketing, Product Management Roles: Content Marketer, Product Manager, UX Writer Specialties: API, Word Documents Tools: Quarto Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 57beae14195562148b1cb9409cd95228df52265d0d7ace639004014f8b95df16 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.