| name | quarto |
| description | Formatting, structure, and execution rules for Quarto markdown documents.
Trigger when:
- Writing, editing, or rendering Quarto documents, reports, presentations, or websites.
- Files matching the pattern **/*.qmd are in the workspace or referenced.
- Tasks involve: quarto render, quarto preview, knitr, jupyter.
- Prompt contains keywords: quarto, qmd, yaml header, code chunk, callout, cross-reference.
|
Quarto (.qmd) Authoring Rules
Quarto is a superset of Pandoc Markdown. It prioritizes semantic structure over visual formatting.
Golden Rule: Never use raw HTML tags (<div>, <img>, <br>) unless absolutely necessary. Use Pandoc Fenced Divs and Spans.
Official Documentation: quarto.org/docs is the authoritative reference. Consult it for edge cases, advanced features, or when this skill lacks specifics.
1. Block Structure (Fenced Divs)
Quarto uses Fenced Divs (:::) to define layout, callouts, and structural blocks. More colons (:::::) enable nesting.
Callouts (Alerts)
Convert standard Markdown blockquotes (>) into semantic callouts.
| Type | Syntax | Use Case |
|---|
| Note | ::: {.callout-note} | Non-critical info |
| Tip | ::: {.callout-tip} | Best practices/optimizations |
| Important | ::: {.callout-important} | Key constraints |
| Warning | ::: {.callout-warning} | Failure modes |
| Caution | ::: {.callout-caution} | Data loss risks |
Features:
- Title: Use a
## heading inside, or the title="..." attribute.
- Collapse: Add
collapse="true" for expandable callouts (collapsed by default).
- Appearance:
appearance="simple" or appearance="minimal" for alternate styles.
- Icons:
icon=false to suppress the default icon.
::: {.callout-caution collapse="true" appearance="simple"}
## Warning Title
Collapsible content.
:::
Multi-Column Layouts
Do not use HTML tables or CSS grids for layout. Use Quarto layout divs.
:::: {.columns}
::: {.column width="40%"}
Left content (e.g., text)
:::
::: {.column width="60%"}
Right content (e.g., image or code)
:::
::::
Tabsets
Group content into switchable tabs using the .panel-tabset class.
::: {.panel-tabset}
## Python
Python code here...
## R
R code here...
:::
Layout Classes
Control content width using column classes:
| Class | Width |
|---|
.column-body | Default text column |
.column-page | Extends into page margins |
.column-screen | Full viewport width |
.column-margin | Right margin (for notes, asides) |
::: {.column-margin}
This appears in the margin.
:::
::: {.column-page}
:::
2. Cross-Referencing (Strict)
Quarto requires specific ID prefixes for automatic numbering. Do not manually number sections, figures, or tables.
The Prefix Rule
You MUST use these prefixes in curly braces {#...} to enable referencing:
| Element | Prefix | Example ID | Reference Syntax |
|---|
| Figures | fig- | {#fig-arch} | @fig-arch |
| Tables | tbl- | {#tbl-stats} | @tbl-stats |
| Sections | sec- | {#sec-deploy} | @sec-deploy |
| Equations | eq- | {#eq-perf} | @eq-perf |
| Listings | lst- | {#lst-main} | @lst-main |
| Theorems | thm- | {#thm-main} | @thm-main |
| Lemmas | lem- | {#lem-helper} | @lem-helper |
| Corollaries | cor- | {#cor-result} | @cor-result |
| Propositions | prp- | {#prp-claim} | @prp-claim |
| Conjectures | cnj- | {#cnj-open} | @cnj-open |
| Definitions | def- | {#def-term} | @def-term |
| Examples | exm- | {#exm-basic} | @exm-basic |
| Exercises | exr- | {#exr-prob1} | @exr-prob1 |
| Solutions | sol- | {#sol-ans} | @sol-ans |
| Algorithms | alg- | {#alg-sort} | @alg-sort |
LaTeX Warning: Avoid underscores (_) in IDs. They cause issues when rendering to PDF.
Reserved Prefixes (full list): fig, tbl, lst, tip, nte, wrn, imp, cau, thm, lem, cor, prp, cnj, def, exm, exr, sol, rem, alg, eq, sec
Wrong: See [Figure 1](#figure-1)
Right: See @fig-arch
Figure Syntax
Images require an ID and a caption (the alt text) to be treated as a Figure.
{#fig-arch}
Subfigures use a parent div with layout-ncol:
::: {#fig-panels layout-ncol=2}
{#fig-first}
{#fig-second}
Panel caption here.
:::
Table Syntax
Tables must have a caption definition (: ...) and an ID to be referenceable.
| Component | Status |
| :-------- | :----- |
| API | Stable |
: System Status {#tbl-status}
Column Widths: Use tbl-colwidths to control proportions:
: Caption {#tbl-id tbl-colwidths="[60,40]"}
Grid Tables
For complex cells (lists, code blocks, multiple paragraphs), use grid tables:
+---------------+---------------+
| Fruit | Advantages |
+===============+===============+
| Bananas | - Portable |
| | - Bright |
+---------------+---------------+
| Oranges | - Vitamin C |
| | - Tasty |
+---------------+---------------+
: Grid table with lists {#tbl-grid}
3. Code Blocks & Execution
Distinguish between Display Code and Executable Code.
Display Only (Standard Markdown)
Use standard triple backticks for static snippets.
```rust
fn main() { ... }
```
Executable Code (Computation)
Use curly braces {python} to indicate the engine should execute the block. Use hash-pipes #| for options.
```{python}
#| label: fig-plot
#| fig-cap: "Performance metrics"
#| echo: false
import matplotlib.pyplot as plt
plt.plot([1,2,3])
```
Execution Options
Options can be set globally (in YAML execute: block) or per-cell (with #|).
| Option | Values | Effect |
|---|
eval | true, false | Whether to run the code |
echo | true, false, fenced | Show source code in output |
output | true, false, asis | Show/suppress output; asis = raw markdown |
warning | true, false | Show/hide warnings |
error | true, false | Allow errors (true continues on error) |
include | true, false | Include cell in output at all |
code-fold | true, false, show | Collapsible source code |
4. Diagrams (Mermaid)
Do not use images for diagrams if they can be defined as code. Quarto renders Mermaid natively.
```{mermaid}
%%| label: fig-flow
%%| fig-cap: "Authentication Flow"
sequenceDiagram
User->>API: Request
API-->>User: Response
```
5. Metadata & Configuration (YAML)
Document Header
Every .qmd file should start with YAML frontmatter.
---
title: "Technical Specification"
author: "Engineering Team"
date: last-modified
format:
html:
toc: true
number-sections: true
code-fold: true
theme: cosmo
pdf:
toc: true
number-sections: true
---
Global Execution Options
execute:
echo: true
warning: false
freeze: auto
Project Configuration (_quarto.yml)
For multi-document projects (books, websites):
project:
type: book
book:
title: "My Book"
chapters:
- index.qmd
- intro.qmd
- part: "Main Content"
chapters:
- chapter1.qmd
- chapter2.qmd
6. Shortcodes (Special Features)
Use Quarto shortcodes {{< ... >}} for special elements.
| Shortcode | Purpose |
|---|
{{< pagebreak >}} | Force a page break (PDF/Docx) |
{{< include _file.qmd >}} | Embed another file (partial) |
{{< embed notebook.ipynb#cell >}} | Embed output from another notebook/qmd |
{{< video src >}} | Embed video players |
{{< var version >}} | Insert variable from _variables.yml |
{{< meta title >}} | Insert value from document metadata |
{{< env VAR_NAME >}} | Insert environment variable |
Include/Embed Rules:
- Shortcodes must appear on their own line, surrounded by blank lines.
- Use absolute paths from project root for reliability.
7. Citations & Bibliography
Quarto uses Pandoc citation syntax with a bibliography file.
YAML Setup:
---
bibliography: references.bib
csl: apa.csl
---
Citation Syntax:
| Syntax | Renders As |
|---|
[@smith2023] | (Smith 2023) |
@smith2023 | Smith (2023) inline |
[@smith2023, p. 42] | (Smith 2023, p. 42) |
[-@smith2023] | (2023) — suppress author |
[@a; @b] | Multiple citations |
8. Raw Format Blocks
Embed format-specific content (ignored in other formats):
```{=latex}
\begin{center}
LaTeX-only content
\end{center}
```
```{=html}
<details><summary>HTML-only</summary>Content</details>
```
Inline: Use `\LaTeX`{=latex} for inline raw content.
9. Inline Spans
Apply attributes to inline text using [text]{.class #id key="value"}.
This is [important text]{.highlight} with inline styling.
Anti-Patterns
| Anti-Pattern | Description | Remedy |
|---|
| Raw HTML | <div class="alert"> | Use ::: {.callout-note} |
| Hardcoded Numbers | "As seen in Figure 3" | Use "As seen in @fig-xyz" |
| Manual TOC | Writing out a list of links | Use toc: true in YAML |
| Remote Images | Hotlinking images | Download to /images or use repo-relative paths |
| Empty Lines | Using <br> for spacing | Use CSS classes or margin attributes |
| Underscores in IDs | {#my_figure_1} | Use hyphens: {#my-figure-1} |
Migration Checklist (Markdown → Quarto)
- Header: Add YAML frontmatter with
title, format, and toc.
- Alerts: Regex replace
> **Note:** with ::: {.callout-note} blocks.
- Images: Add
{#fig-name} to all image links that need captions.
- Links: Convert local section links
[Link](#heading) to @sec-heading.
- Diagrams: Convert static diagram images to
mermaid blocks where possible.
- IDs: Replace underscores with hyphens in all identifiers.
- Tabsets: Convert manual tab implementations to
::: {.panel-tabset}.
- Citations: Convert manual citations to
[@key] with a .bib file.
- Project: For multi-file docs, create
_quarto.yml to define structure.
Output Formats
Quarto supports multiple output formats via the format: key:
| Format | Value | Notes |
|---|
| HTML | html | Default, interactive |
| PDF | pdf | Requires LaTeX |
| Word | docx | MS Word |
| Presentation | revealjs | Slides via Reveal.js |
| Book | book | Multi-chapter (in _quarto.yml) |
| Typst | typst | Modern PDF alternative |
format:
html: default
pdf:
documentclass: article
revealjs:
theme: dark
