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}
![Wide figure](wide.png)
:::

---

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.

![System Architecture Diagram](images/arch.png){#fig-arch}

Subfigures use a parent div with layout-ncol:

::: {#fig-panels layout-ncol=2}

![First](a.png){#fig-first}

![Second](b.png){#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 # Show code by default
  warning: false # Hide warnings
  freeze: auto # Only re-execute changed documents

Project Configuration (_quarto.yml)

For multi-document projects (books, websites):

project:
  type: book # or: website, manuscript, default

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 # Optional: citation style
---

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)

1. Header: Add YAML frontmatter with title, format, and toc.
2. Alerts: Regex replace > **Note:** with ::: {.callout-note} blocks.
3. Images: Add {#fig-name} to all image links that need captions.
4. Links: Convert local section links [Link](#heading) to @sec-heading.
5. Diagrams: Convert static diagram images to mermaid blocks where possible.
6. IDs: Replace underscores with hyphens in all identifiers.
7. Tabsets: Convert manual tab implementations to ::: {.panel-tabset}.
8. Citations: Convert manual citations to [@key] with a .bib file.
9. 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