# Callouts

Callouts are specially formatted blocks for notes, warnings, tips, and other highlighted content.

## Callout Types

Five built-in types: `note`, `warning`, `important`, `tip`, `caution`.

```markdown
::: {.callout-note}
This is a note callout.
:::
```

Replace `note` with any other type (`warning`, `important`, `tip`, `caution`) for the corresponding style.

## Custom Titles

Use a heading for custom title:

```markdown
::: {.callout-note}

## Custom Title Here

Content of the callout.

:::
```

Or use `title` attribute:

```markdown
::: {.callout-note title="My Custom Title"}
Content of the callout.
:::
```

## Appearance Options

Three styles: `default` (colored header with icon), `simple` (lighter, no colored header), `minimal` (borders only).

```markdown
::: {.callout-note appearance="simple"}
Simple appearance.
:::
```

Set document default in YAML:

```yaml
callout-appearance: simple
```

## Collapsible Callouts

```markdown
::: {.callout-tip collapse="true"}

## Expand for Details

Hidden content revealed on click.

:::
```

`collapse="true"` starts collapsed. `collapse="false"` starts expanded but is collapsible. Without `collapse`, the callout is not collapsible.

## Icons

Disable per-callout or document-wide:

```markdown
::: {.callout-note icon="false"}
No icon on this callout.
:::
```

```yaml
callout-icon: false
```

## Cross-Referenceable Callouts

Add an ID with the appropriate prefix to reference callouts:

```markdown
::: {#nte-important .callout-note}

## Important Information

This callout can be referenced.

:::

See @nte-important for details.
```

### Callout Prefixes

| Type      | Prefix |
| --------- | ------ |
| Note      | `nte-` |
| Tip       | `tip-` |
| Warning   | `wrn-` |
| Important | `imp-` |
| Caution   | `cau-` |

## Nested Callouts

Nest callouts inside each other:

````markdown
::: {.callout-note}

## Outer Callout

::: {.callout-tip}
Nested callout.
:::

:::
````

## Format-Specific Options

```yaml
# HTML
format:
  html:
    callout-appearance: simple
    callout-icon: true

# PDF
format:
  pdf:
    callout-appearance: default
```

RevealJS supports callouts but `collapse` is not available.

## Styling Callouts

### Custom CSS (HTML)

```css
.callout-note {
  border-left-color: #0066cc;
}

.callout-note .callout-title {
  background-color: #e6f0ff;
}
```

### SCSS Variables

```scss
$callout-color-note: #0066cc;
$callout-color-tip: #00cc66;
```

## Summary of Attributes

| Attribute         | Values                                           | Description      |
| ----------------- | ------------------------------------------------ | ---------------- |
| `.callout-{type}` | `note`, `warning`, `important`, `tip`, `caution` | Callout type     |
| `appearance`      | `default`, `simple`, `minimal`                   | Visual style     |
| `collapse`        | `true`, `false`                                  | Make collapsible |
| `icon`            | `true`, `false`                                  | Show/hide icon   |
| `title`           | String                                           | Custom title     |
| `#id`             | `nte-`, `tip-`, `wrn-`, `imp-`, `cau-` + name    | For cross-refs   |

Callouts support any markdown content including lists, code blocks, images, and multiple paragraphs.

## Resources

- [Quarto Callouts](https://quarto.org/docs/authoring/callouts.html)

# Citations and Footnotes

Quarto uses Pandoc's citation system with support for BibTeX, CSL styles, and flexible citation formatting.

## Citation Syntax

### Basic Citations

````markdown
According to @smith2020, the results indicate...
The study showed significant results [@smith2020].
````

### Variations

| Syntax                | Output                     |
| --------------------- | -------------------------- |
| `@smith2020`          | Smith (2020)               |
| `[@smith2020]`        | (Smith 2020)               |
| `[-@smith2020]`       | (2020) - author suppressed |
| `@Smith2020 [p. 10]`  | Smith (2020, p. 10)        |
| `[@smith2020, p. 10]` | (Smith 2020, p. 10)        |

### Multiple Citations

````markdown
Several studies [@smith2020; @jones2021] found...
[@smith2020; @jones2021; @williams2022]
````

### Citation with Locators

````markdown
@smith2020 [p. 33]
@smith2020 [chap. 2]
[@smith2020, pp. 10-15]
[@smith2020, fig. 3]
````

Common locators: `p.`, `pp.`, `chap.`, `sec.`, `fig.`, `eq.`, `vol.`.

### In-Text vs Parenthetical

````markdown
@smith2020 says... → Smith (2020) says...
As shown by @smith2020... → As shown by Smith (2020)...
The results [@smith2020]... → The results (Smith 2020)...
````

### Prefix and Suffix

````markdown
[see @smith2020, pp. 10-15, for discussion]
→ (see Smith 2020, pp. 10-15, for discussion)
````

## Bibliography Configuration

### Basic Setup

```yaml
bibliography: references.bib
```

### Multiple Files

```yaml
bibliography:
  - references.bib
  - additional.bib
```

### BibTeX File Example

```bibtex
@article{smith2020,
  author = {Smith, John},
  title = {Article Title},
  journal = {Journal Name},
  year = {2020},
  volume = {10},
  pages = {1-20}
}

@book{jones2021,
  author = {Jones, Sarah},
  title = {Book Title},
  publisher = {Publisher},
  year = {2021}
}
```

### Other Formats

Quarto supports:

- BibTeX (`.bib`)
- BibLaTeX (`.bib`)
- CSL JSON (`.json`)
- CSL YAML (`.yaml`)

## Citation Styles (CSL)

### Specify CSL File

```yaml
bibliography: references.bib
csl: apa.csl
```

### Find CSL Files

- [Zotero Style Repository](https://www.zotero.org/styles)
- [CSL Repository](https://github.com/citation-style-language/styles)

### Common Styles

```yaml
csl: apa.csl           # APA 7th edition
csl: chicago-author-date.csl
csl: ieee.csl
csl: nature.csl
csl: vancouver.csl
```

## Bibliography Placement

By default, bibliography appears at end. Control placement:

````markdown
## References

::: {#refs}
:::

## Appendix

Additional content after references.
````

### Suppress Bibliography

```yaml
suppress-bibliography: true
```

## Footnotes

### Inline Footnotes

````markdown
This is text with a footnote.^[This is the footnote content.]
````

### Reference Footnotes

````markdown
This is text with a footnote.[^1]

[^1]: This is the footnote content.
````

### Multi-Paragraph Footnotes

````markdown
[^longnote]: This is a long footnote.

    It has multiple paragraphs.

    And can include code:

    ```{.r}
    x <- 1
    ```
````

## Citation Methods

### Citeproc (Default)

Standard Pandoc citation processing:

```yaml
bibliography: references.bib
```

### BibLaTeX (PDF)

```yaml
bibliography: references.bib
format:
  pdf:
    cite-method: biblatex
```

### Natbib (PDF)

```yaml
bibliography: references.bib
format:
  pdf:
    cite-method: natbib
```

## Reference Section Title

```yaml
reference-section-title: "References"
```

Or for other languages:

```yaml
lang: de
reference-section-title: "Literaturverzeichnis"
```

## Citation Links

Control hyperlinking:

```yaml
link-citations: true # Link in-text to bibliography
link-bibliography: true # Link URLs in bibliography
```

## Citation Processing Options

```yaml
citeproc: true # Enable citation processing
citation-abbreviations: abbrev.json # Journal abbreviations
notes-after-punctuation: true
```

## DOI and URL Handling

```yaml
format:
  html:
    citations:
      link-citations: true
  pdf:
    include-in-header:
      - text: |
          \usepackage{hyperref}
```

## Footnote Location

Control where footnotes appear:

```yaml
reference-location: document   # End of document
reference-location: section    # End of section
reference-location: block      # End of block
reference-location: margin     # In margin (if supported)
```

## Citation Hover (HTML)

Enable hover previews:

```yaml
format:
  html:
    citation-hover: true
```

## Author-Date vs Numeric

Controlled by CSL style:

```yaml
# Author-date style
csl: apa.csl

# Numeric style
csl: ieee.csl
```

## Citing Software

```bibtex
@software{tidyverse,
  author = {Wickham, Hadley},
  title = {tidyverse: Easily Install and Load the 'Tidyverse'},
  year = {2023},
  url = {https://CRAN.R-project.org/package=tidyverse}
}
```

Or use `@Manual` for R packages.

## Resources

- [Quarto Citations](https://quarto.org/docs/authoring/citations.html)
- [Pandoc Citations](https://pandoc.org/MANUAL.html#citations)
- [CSL Styles](https://citationstyles.org/)

# Code Cells

Quarto uses a hashpipe (`#|`) syntax for code cell options, providing a clean, YAML-based approach that works across R, Python, Julia, and other languages.

## Hashpipe Syntax

Code cell options are specified with `#|` at the start of lines within the code block:

````markdown
```{language}
#| label: fig-scatter
#| echo: false
#| fig-cap: "A scatter plot of x versus y."
#| fig-width: 8
#| fig-height: 6

# code that produces a scatter plot
```
````

**Important:** Options use **dashes, not dots**. Use `fig-cap` not `fig.cap`, `fig-width` not `fig.width`.

The hashpipe prefix is `#|` for R, Python, and Julia; diagram cells use a different prefix. See [engines.md](engines.md) for the full table.

## Execution Options

Control whether and how code is executed:

| Option    | Description                               | Values                    |
| --------- | ----------------------------------------- | ------------------------- |
| `eval`    | Evaluate the code                         | `true`, `false`           |
| `echo`    | Include source code in output             | `true`, `false`, `fenced` |
| `output`  | Include results in output                 | `true`, `false`, `asis`   |
| `warning` | Include warnings                          | `true`, `false`           |
| `error`   | Include errors (stop on error if `false`) | `true`, `false`           |
| `include` | Include cell in output at all             | `true`, `false`           |

### Examples

Show code but don't run it:

````markdown
```{language}
#| eval: false

# This code is displayed but not executed
```
````

Run code but hide it:

````markdown
```{language}
#| echo: false

# This code runs but is not shown
```
````

Show fenced code block with attributes:

````markdown
```{language}
#| echo: fenced

# code here
```
````

### output: asis

`output: asis` passes the cell output through as raw content without further Quarto processing.
Use it when your code prints a pre-formatted markdown or raw string that Quarto should treat as document content.

Requirements:

- The output must already be valid markdown (pipe table, headings, prose) or a raw block (` ```{=html} `, ` ```{=latex} `).
- `tbl-cap` on an `output: asis` cell does not behave identically to the knitr table-rendering path; prefer a div-wrapped caption for reliability.

````markdown
```{language}
#| output: asis

# print("| Col A | Col B |\n| ----- | ----- |\n| 1     | 2     |")
```
````

## Figure Options

Options for controlling figure output:

| Option             | Description                      | Example                         |
| ------------------ | -------------------------------- | ------------------------------- |
| `fig-cap`          | Figure caption                   | `"A descriptive caption."`      |
| `fig-subcap`       | Subcaptions for multiple figures | `["Plot A", "Plot B"]`          |
| `fig-width`        | Width in inches                  | `8`                             |
| `fig-height`       | Height in inches                 | `6`                             |
| `fig-alt`          | Alt text for accessibility       | `"Scatter plot showing..."`     |
| `fig-align`        | Alignment                        | `"left"`, `"center"`, `"right"` |
| `fig-cap-location` | Caption position                 | `"top"`, `"bottom"`, `"margin"` |
| `fig-format`       | Output format                    | `"png"`, `"svg"`, `"pdf"`       |
| `fig-dpi`          | Resolution in DPI                | `300`                           |

### Figure Example

````markdown
```{language}
#| label: fig-analysis
#| fig-cap: "Analysis results showing the relationship between variables."
#| fig-alt: "Scatter plot with trend line showing positive correlation."
#| fig-width: 10
#| fig-height: 6
#| fig-align: center

# code that produces a scatter plot with trend line
```
````

### Multiple Figures

````markdown
```{language}
#| label: fig-panels
#| fig-cap: "Multiple panel figure."
#| fig-subcap:
#|   - "Distribution of X"
#|   - "Distribution of Y"
#| layout-ncol: 2

# code that produces two figures (one per panel)
```
````

## Table Options

Options for controlling table output:

| Option             | Description                     | Example                         |
| ------------------ | ------------------------------- | ------------------------------- |
| `tbl-cap`          | Table caption                   | `"Summary statistics."`         |
| `tbl-subcap`       | Subcaptions for multiple tables | `["Table A", "Table B"]`        |
| `tbl-colwidths`    | Column widths                   | `[40, 60]` or `"auto"`          |
| `tbl-cap-location` | Caption position                | `"top"`, `"bottom"`, `"margin"` |

### Table Example

````markdown
```{language}
#| label: tbl-summary
#| tbl-cap: "Summary statistics by group."

# code that produces a table
```
````

Table rendering behaviour differs between the knitr and jupyter engines; see [tables.md](tables.md) for details.
For markdown table output from code, use `output: asis` (see the [output: asis](#output-asis) section above).

## Caching and Freeze

Only suggest `#| cache: true` for R code cells (knitr engine).
It is not valid for Python or Julia cells — the jupyter engine silently ignores it.

For Python and Julia, caching is document-level only.
Install `jupyter-cache` (`pip install jupyter-cache`) and set in YAML front matter:

```yaml
execute:
  cache: true
```

For details see <https://quarto.org/docs/projects/code-execution.html#cache>.

### Project-Level Freeze

In `_quarto.yml`:

```yaml
execute:
  freeze: auto # Re-render only when source changes
```

## Document-Level Defaults

Set defaults for all code cells in YAML front matter:

```yaml
title: "My Document"
execute:
  echo: false
  warning: false
  message: false
```

Or per-format:

```yaml
format:
  html:
    code-fold: true
  pdf:
    echo: false
```

## Code Display Options

Control how code is displayed in HTML output:

| Option              | Description          | Values                    |
| ------------------- | -------------------- | ------------------------- |
| `code-fold`         | Collapsible code     | `true`, `false`, `"show"` |
| `code-summary`      | Text for fold toggle | `"Show code"`             |
| `code-tools`        | Code tools menu      | `true`, `false`           |
| `code-line-numbers` | Show line numbers    | `true`, `false`           |
| `code-overflow`     | Handle overflow      | `"scroll"`, `"wrap"`      |

### Code Folding

In YAML front matter:

```yaml
format:
  html:
    code-fold: true
    code-summary: "Click to see code"
```

Per cell override:

````markdown
```{language}
#| code-fold: show

# This code is visible by default
```
````

## Code Annotations

Add annotations to explain code:

````markdown
```{language}
#| code-annotations: hover

step_one()   # <1>
step_two()   # <2>
step_three() # <3>
```
````

1. First step description.
2. Second step description.
3. Third step description.

Annotation styles: `hover`, `select`, `below`, `beside`.

## Filename Display

Show a filename above the code block:

````markdown
```{language}
#| filename: "analysis.ext"

# code here
```
````

## R Markdown Migration

R Markdown uses dots (`.`), Quarto uses dashes (`-`): `fig.cap` → `fig-cap`, `fig.width` → `fig-width`. Options move from chunk header to `#|` lines. `results="asis"` becomes `output: asis`. Setup chunks with `knitr::opts_chunk$set(...)` become `execute:` in YAML. See [conversion-rmarkdown.md](conversion-rmarkdown.md) for full details.

## Resources

- [Quarto Execution Options](https://quarto.org/docs/computations/execution-options.html)
- [Code Annotation](https://quarto.org/docs/authoring/code-annotation.html)
- [Code Cells: Knitr](https://quarto.org/docs/reference/cells/cells-knitr.html)
- [Code Cells: Jupyter](https://quarto.org/docs/reference/cells/cells-jupyter.html)

# Conditional Content

Quarto allows content to be shown or hidden based on output format, metadata, or profiles.

## Format-Based Conditions

### Content Visible

Show content only for specific formats:

```markdown
::: {.content-visible when-format="html"}
This only appears in HTML output.
:::
```

### Content Hidden

Hide content for specific formats:

```markdown
::: {.content-hidden when-format="pdf"}
This appears everywhere except PDF.
:::
```

### Unless Format

Show unless a specific format:

```markdown
::: {.content-visible unless-format="html"}
This appears in PDF, DOCX, etc., but not HTML.
:::
```

## Format Values

### Single Formats

| Format          | Value      |
| --------------- | ---------- |
| HTML            | `html`     |
| PDF             | `pdf`      |
| Word            | `docx`     |
| LaTeX           | `latex`    |
| RevealJS        | `revealjs` |
| Beamer          | `beamer`   |
| EPUB            | `epub`     |
| GitHub Markdown | `gfm`      |

### Format Aliases

Quarto groups related formats:

| Alias     | Includes                             |
| --------- | ------------------------------------ |
| `html`    | HTML, EPUB, RevealJS, Dashboard      |
| `pdf`     | PDF, LaTeX, Beamer                   |
| `html:js` | HTML formats with JavaScript support |

### Example with Aliases

```markdown
::: {.content-visible when-format="pdf"}
This appears in PDF, LaTeX, and Beamer.
:::
```

## Multiple Formats

### Either Format

```markdown
::: {.content-visible when-format="html"}
::: {.content-visible when-format="revealjs"}
This appears in HTML or RevealJS.
:::
:::
```

Or use aliases:

```markdown
::: {.content-visible when-format="html"}
Appears in all HTML-based formats.
:::
```

## Inline Conditions

For inline content, use spans:

```markdown
View the [interactive version]{.content-visible when-format="html"}
[figure]{.content-visible when-format="pdf"}.
```

## Metadata-Based Conditions

### When Meta

Show based on metadata values:

```markdown
::: {.content-visible when-meta="draft"}
DRAFT - Not for distribution.
:::
```

With YAML:

```yaml
draft: true
```

### Unless Meta

```markdown
::: {.content-visible unless-meta="draft"}
Final version content.
:::
```

### Nested Metadata

```markdown
::: {.content-visible when-meta="params.show-advanced"}
Advanced content here.
:::
```

YAML:

```yaml
params:
  show-advanced: true
```

## Profile-Based Conditions

### Define Profiles

In `_quarto.yml`:

```yaml
profile:
  default: production

  group:
    - [development, production]
```

### Profile-Specific Content

```markdown
::: {.content-visible when-profile="development"}
Debug information here.
:::

::: {.content-visible when-profile="production"}
Production content only.
:::
```

### Using Profiles

```bash
quarto render --profile development
```

## Conditional Code Blocks

### Format-Specific Code

````markdown
::: {.content-visible when-format="html"}

```{language}
# interactive output for HTML
```

:::

::: {.content-visible when-format="pdf"}

```{language}
# static output for PDF
```

:::
````

### With QUARTO_EXECUTE_INFO

Quarto creates a JSON file with execution context information. Read it to conditionally execute code in any language.

#### R

````markdown
```{r}
quarto_info <- jsonlite::read_json(
  Sys.getenv("QUARTO_EXECUTE_INFO")
)
if (quarto_info$output$format == "html") {
  interactive_plot()
}
```
````

#### Python

````markdown
```{python}
import os
import json

with open(os.environ["QUARTO_EXECUTE_INFO"]) as f:
    quarto_info = json.load(f)

if quarto_info["output"]["format"] == "html":
    interactive_plot()
```
````

See [QUARTO_EXECUTE_INFO](https://quarto.org/docs/advanced/quarto-execute-info.html) for available fields.

## Conditional Includes

Include different files based on format:

```markdown
::: {.content-visible when-format="html"}

{{< include _interactive-content.qmd >}}

:::

::: {.content-visible when-format="pdf"}

{{< include _static-content.qmd >}}

:::
```

## Conditional YAML

Use conditional logic in YAML:

```yaml
format:
  html:
    include-in-header:
      - text: |
          <script src="interactive.js"></script>
  pdf:
    include-in-header:
      - text: |
          \usepackage{custom}
```

## Complex Conditions

### Combining Conditions

```markdown
::: {.content-visible when-format="html" when-meta="interactive"}
Interactive HTML content.
:::
```

Both conditions must be true.

### Nested Conditions

```markdown
::: {.content-visible when-format="html"}

::: {.content-visible when-meta="advanced"}
Advanced HTML content.
:::

Basic HTML content.

:::
```

## Resources

- [Quarto Conditional Content](https://quarto.org/docs/authoring/conditional.html)
- [Project Profiles](https://quarto.org/docs/projects/profiles.html)

# Converting blogdown to Quarto

Guide for converting blogdown (Hugo-based) sites to Quarto websites or blogs.

## Overview

Key differences:

1. Configuration: `config.toml` or `config.yaml` → `_quarto.yml`
2. Content: Hugo templates → Quarto layouts
3. Shortcodes: Hugo → Quarto shortcodes
4. Themes: Hugo themes → Quarto themes

## Quick Start

### 1. Create Quarto Config

Replace `config.toml` or `config.yaml` with `_quarto.yml`:

```yaml
project:
  type: website

website:
  title: "My Site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo
```

### 2. Rename Files

```bash
for f in content/**/*.Rmd; do
  mv "$f" "${f%.Rmd}.qmd"
done
```

### 3. Update Front Matter

#### Blogdown

```yaml
title: "Post Title"
author: "Author"
date: "2024-01-15"
slug: "post-slug"
categories: ["R"]
tags: ["data"]
```

#### Quarto

```yaml
title: "Post Title"
author: "Author"
date: 2024-01-15
categories:
  - R
  - data
```

## Project Structure

### blogdown

```txt
config.toml (or config.yaml)
content/
  _index.md
  about.md
  post/
    2024-01-01-first/
      index.Rmd
static/
  images/
themes/
  hugo-theme/
public/
```

### Quarto

```txt
_quarto.yml
index.qmd
about.qmd
posts/
  first-post/
    index.qmd
images/
_site/
```

## Configuration Mapping

### Basic Site Config

#### Blogdown (`config.yaml`)

```yaml
baseURL: "https://example.com/"
title: "My Site"
theme: "hugo-theme"

params:
  description: "Site description"
  author: "Author Name"

menu:
  main:
    - name: "Home"
      url: "/"
      weight: 1
    - name: "About"
      url: "/about/"
      weight: 2
```

#### Quarto (`_quarto.yml`)

```yaml
project:
  type: website
  output-dir: _site

website:
  title: "My Site"
  description: "Site description"
  site-url: https://example.com/
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: blog.qmd
        text: Blog

format:
  html:
    theme: cosmo

author: "Author Name"
```

The same mapping applies to `config.toml` — convert TOML keys to the equivalent Quarto YAML.

## Blog Setup

### Listing Page

Create `blog.qmd`:

```yaml
title: "Blog"
listing:
  contents: posts
  type: default
  sort: "date desc"
  categories: true
  feed: true
```

### Post Structure

```txt
posts/
  2024-01-15-first-post/
    index.qmd
    images/
      figure1.png
  2024-01-20-second-post/
    index.qmd
```

### Post Front Matter

```yaml
title: "Post Title"
description: "Brief description for listing"
author: "Author Name"
date: 2024-01-15
categories:
  - R
  - Tutorial
image: images/preview.png
draft: false
```

## Hugo Shortcodes

### Figure

#### Hugo

````markdown
{{</* figure src="image.png" caption="Caption" */>}}
````

#### Quarto

````markdown
![Caption](image.png)
````

### Tweet

#### Hugo

````markdown
{{</* tweet user="username" id="1234567890" */>}}
````

#### Quarto (with extension)

````markdown
{{< tweet username 1234567890 >}}
````

Install extension: `quarto add sellorm/quarto-social-embeds`

### YouTube

#### Hugo

````markdown
{{</* youtube VIDEO_ID */>}}
````

#### Quarto

````markdown
{{< video https://www.youtube.com/embed/VIDEO_ID >}}
````

### Gist

#### Hugo

````markdown
{{</* gist user gist_id */>}}
````

### Highlight

#### Hugo

````markdown
{{</* highlight r */>}}
code here
{{</* /highlight */>}}
````

#### Quarto

````markdown
```{.r}
code here
```
````

or

````markdown
```r
code here
```
````

### Ref/Relref

#### Hugo

````markdown
[Link]({{</* ref "other-post.md" */>}})
````

#### Quarto

````markdown
[Link](other-post.qmd)
````

## Taxonomies

### blogdown Categories and Tags

```yaml
categories: ["R", "Data Science"]
tags: ["ggplot2", "visualization"]
```

### Quarto Categories

```yaml
categories:
  - R
  - Data Science
  - ggplot2
  - visualization
```

Enable category listing:

```yaml
# In blog.qmd
listing:
  contents: posts
  categories: true
```

## Static Files

### blogdown

Static files in `static/` are copied to site root.

### Quarto

Put files in project root or use `resources`:

```yaml
# _quarto.yml
project:
  resources:
    - images/
    - files/
```

## Themes and Styling

### blogdown

Uses Hugo themes from `themes/` directory.

### Quarto

Use built-in themes or custom SCSS:

```yaml
format:
  html:
    theme:
      - cosmo
      - custom.scss
```

### Custom SCSS

```scss
// custom.scss
$body-bg: #ffffff;
$body-color: #333333;
$link-color: #0066cc;

// Custom rules
.quarto-title {
  font-size: 2.5rem;
}
```

## RSS Feed

### blogdown

Hugo generates RSS automatically.

### Quarto

Enable in listing:

- `blog.qmd`

  ````markdown
  ---
  listing:
    feed: true
  ---
  ````

Or in `_quarto.yml`:

```yaml
website:
  site-url: https://example.com

listing:
  feed:
    title: "My Blog"
    description: "Blog description"
```

## Comments

### Quarto

In `_quarto.yml`:

```yaml
website:
  comments:
    giscus:
      repo: username/repo
      category: "Comments"
```

Or per-post:

```yaml
comments:
  giscus:
    repo: username/repo
```

## Syntax Highlighting

### blogdown

Configured in Hugo config or theme.

### Quarto

```yaml
format:
  html:
    highlight-style: github
    code-line-numbers: true
    code-fold: true
```

## Draft Posts

### blogdown

```yaml
draft: true
```

### Quarto

Same syntax:

```yaml
draft: true
```

Render drafts with:

```bash
quarto render --profile drafts
```

With profile config:

```yaml
# _quarto-drafts.yml
execute:
  echo: true

website:
  drafts: true
```

## Deployment

### Netlify

```yaml
# netlify.toml
[build]
  command = "quarto render"
  publish = "_site"
```

### GitHub Pages

```yaml
# .github/workflows/publish.yml
name: Publish

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: quarto-dev/quarto-actions/setup@v2
      - run: quarto render
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site
```

## Common Issues

### Missing Shortcodes

Install Quarto extensions for missing functionality.

### Broken Internal Links

Update `.md` and `.Rmd` extensions to `.qmd`.

### Theme Differences

Quarto themes differ from Hugo themes; expect visual changes.

### Build Errors

Check for Hugo-specific template syntax in content files.

## Resources

- [Quarto Websites](https://quarto.org/docs/websites/)
- [Quarto Blogs](https://quarto.org/docs/websites/website-blog.html)
- [Quarto Themes](https://quarto.org/docs/output-formats/html-themes.html)

# Converting bookdown to Quarto

Guide for converting bookdown projects to Quarto book format.

## Overview

Key differences:

1. Configuration file: `_bookdown.yml` → `_quarto.yml`
2. Cross-references: `\@ref()` → `@`
3. Chapter organization
4. Theorem environments

## Quick Start

### 1. Create Quarto Config

Replace `_bookdown.yml` with `_quarto.yml`:

```yaml
project:
  type: book

book:
  title: "My Book"
  author: "Author Name"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: book
```

### 2. Rename Files

```bash
for f in *.Rmd; do mv "$f" "${f%.Rmd}.qmd"; done
```

### 3. Update Cross-References

#### Bookdown

````markdown
See Figure \@ref(fig:myplot)
See Table \@ref(tab:mytable)
````

#### Quarto

````markdown
See @fig-myplot
See @tbl-mytable
````

## Configuration Mapping

### bookdown (`_bookdown.yml`)

```yaml
book_filename: "my-book"
output_dir: "docs"
delete_merged_file: true
language:
  ui:
    chapter_name: "Chapter "
rmd_files:
  - index.Rmd
  - 01-intro.Rmd
  - 02-methods.Rmd
  - 03-results.Rmd
  - references.Rmd
```

### Quarto (`_quarto.yml`)

```yaml
project:
  type: book
  output-dir: docs

book:
  title: "My Book"
  author: "Author Name"
  date: today
  chapters:
    - index.qmd
    - intro.qmd
    - methods.qmd
    - results.qmd
  appendices:
    - references.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: book
```

## Chapter Organization

### With Parts

```yaml
book:
  chapters:
    - index.qmd
    - part: "Part I: Foundation"
      chapters:
        - basics.qmd
        - setup.qmd
    - part: "Part II: Advanced"
      chapters:
        - advanced1.qmd
        - advanced2.qmd
  appendices:
    - appendix.qmd
```

### Numbered vs Unnumbered

Add `{.unnumbered}` to exclude from numbering:

````markdown
# Preface {.unnumbered}
````

## Cross-Reference Conversion

### Figures

#### bookdown

````markdown
```{r myplot, fig.cap="My figure"}
plot(1:10)
```

See Figure \@ref(fig:myplot).
````

#### Quarto

````markdown
```{r}
#| label: fig-myplot
#| fig-cap: "My figure"

plot(1:10)
```

See @fig-myplot.
````

### Tables

#### bookdown

````markdown
```{r mytable}
knitr::kable(head(iris), caption = "Iris data")
```

See Table \@ref(tab:mytable).
````

#### Quarto

````markdown
```{r}
#| label: tbl-iris
#| tbl-cap: "Iris data"

knitr::kable(head(iris))
```

See @tbl-iris.
````

Note: Quarto uses `tbl-` not `tab-`.

### Equations

#### bookdown

````markdown
# bookdown
\begin{equation}
y = mx + b (\#eq:line)
\end{equation}
See Equation \@ref(eq:line).
````

#### Quarto

````markdown
$$
y = mx + b
$$ {#eq-line}

See @eq-line.
````

### Sections

#### bookdown

````markdown
# Introduction {#intro}

See Section \@ref(intro).
````

#### Quarto

````markdown
# Introduction {#sec-intro}

See @sec-intro.
````

### Theorems

#### bookdown

````markdown
```{theorem, name="Pythagorean"}
For a right triangle, $a^2 + b^2 = c^2$.
```

See Theorem \@ref(thm:pythagorean).
````

#### Quarto

````markdown
::: {#thm-pythagorean}

## Pythagorean Theorem

For a right triangle, $a^2 + b^2 = c^2$.
:::

See @thm-pythagorean.
````

## Theorem Environments

### bookdown

````markdown
```{theorem, label="main", name="Main Theorem"}
Statement here.
```

```{lemma}
Lemma statement.
```

```{proof}
Proof here.
```
````

### Quarto

````markdown
::: {#thm-main}

## Main Theorem

Statement here.

:::

::: {#lem-helper}

## Helper Lemma

Lemma statement.

:::

::: {.proof}
Proof here.
:::
````

Supported types: `thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`.

## Custom Blocks

### bookdown

````markdown
```{block, type='rmdnote'}
This is a note.
```
````

### Quarto

````markdown
::: {.callout-note}
This is a note.
:::
````

## Output Formats

### bookdown

```yaml
output:
  bookdown::gitbook:
    css: style.css
  bookdown::pdf_book:
    includes:
      in_header: preamble.tex
```

### Quarto

```yaml
format:
  html:
    theme: cosmo
    css: style.css
  pdf:
    documentclass: book
    include-in-header: preamble.tex
```

### Format Mapping

| bookdown         | Quarto |
| ---------------- | ------ |
| `gitbook`        | `html` |
| `pdf_book`       | `pdf`  |
| `epub_book`      | `epub` |
| `word_document2` | `docx` |

## Bibliography

### bookdown

```yaml
# _bookdown.yml
bibliography: [book.bib, packages.bib]
```

### Quarto

In `_quarto.yml`:

```yaml
book:
  bibliography: references.bib
```

Or in individual files:

```yaml
bibliography: references.bib
```

## Custom Styling

### HTML

```yaml
format:
  html:
    theme:
      - cosmo
      - custom.scss
    css: styles.css
```

### PDF

```yaml
format:
  pdf:
    documentclass: book
    include-in-header: preamble.tex
```

## Common Issues

### Chapters Not Found

Check file names in `_quarto.yml` match actual files.

### Cross-Reference Not Working

Ensure:

- Label has correct prefix (`fig-`, `tbl-`, etc.)
- Reference uses `@` syntax

### Theorem Numbering Wrong

Check theorem IDs are unique and properly formatted.

## Resources

- [Quarto Books](https://quarto.org/docs/books/)
- [Cross-References](https://quarto.org/docs/authoring/cross-references.html)
- [Theorems](https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs)

# Converting distill to Quarto

Guide for converting distill articles and blogs to Quarto format.

## Overview

Key differences:

1. Format: `distill_article` → `html`
2. Configuration: R YAML → Quarto YAML
3. Asides: `<aside>` → `::: {.column-margin}`
4. Appendices: Heading-based

## Quick Start

### 1. Rename File

```bash
mv article.Rmd article.qmd
```

### 2. Update YAML

#### distill

```yaml
title: "My Article"
author:
  - name: "Jane Doe"
    affiliation: University
output: distill::distill_article
```

#### Quarto

```yaml
title: "My Article"
author:
  - name: "Jane Doe"
    affiliations:
      - University
format: html
```

## YAML Conversion

### Basic Article

#### distill

```yaml
title: "Research Article"
description: "A brief description"
author:
  - name: "Jane Doe"
    url: https://example.com
    affiliation: University Name
    affiliation_url: https://university.edu
    orcid_id: 0000-0000-0000-0000
date: "2024-01-15"
output:
  distill::distill_article:
    toc: true
    toc_depth: 3
```

#### Quarto

```yaml
title: "Research Article"
description: "A brief description"
author:
  - name: "Jane Doe"
    url: https://example.com
    affiliations:
      - name: University Name
        url: https://university.edu
    orcid: 0000-0000-0000-0000
date: 2024-01-15
format:
  html:
    toc: true
    toc-depth: 3
```

### Author Metadata

#### distill

```yaml
author:
  - name: "First Author"
    affiliation: Institution A
    affiliation_url: https://a.edu
  - name: "Second Author"
    affiliation: Institution B
```

#### Quarto

```yaml
author:
  - name: "First Author"
    affiliations:
      - name: Institution A
        url: https://a.edu
  - name: "Second Author"
    affiliations:
      - Institution B
```

### Citation Metadata

#### distill

```yaml
citation_url: https://example.com/article
bibliography: references.bib
```

#### Quarto

```yaml
citation:
  url: https://example.com/article
bibliography: references.bib
```

## Aside Content

### distill

```html
<aside>This content appears in the margin.</aside>
```

Or with R Markdown:

````markdown
::: {.l-body-outset}
Wide content here.
:::
````

### Quarto

````markdown
::: {.column-margin}
This content appears in the margin.
:::
````

Or inline:

````markdown
Main text here.
[This appears in the margin.]{.aside}
````

## Layout Classes

### distill

````markdown
::: {.l-body}
Default body width.
:::

::: {.l-body-outset}
Slightly wider than body.
:::

::: {.l-page}
Page width.
:::

::: {.l-screen}
Full screen width.
:::

::: {.l-screen-inset}
Screen width with padding.
:::
````

### Quarto

````markdown
::: {.column-body}
Default body width.
:::

::: {.column-body-outset}
Slightly wider than body.
:::

::: {.column-page}
Page width.
:::

::: {.column-screen}
Full screen width.
:::

::: {.column-screen-inset}
Screen width with padding.
:::
````

### Layout Mapping

| distill           | Quarto                 |
| ----------------- | ---------------------- |
| `.l-body`         | `.column-body`         |
| `.l-body-outset`  | `.column-body-outset`  |
| `.l-page`         | `.column-page`         |
| `.l-page-outset`  | `.column-page-outset`  |
| `.l-screen`       | `.column-screen`       |
| `.l-screen-inset` | `.column-screen-inset` |
| `.l-gutter`       | `.column-margin`       |

## Figures

### distill

````markdown
```{r, layout="l-body-outset", fig.cap="Caption"}
plot(1:10)
```
````

### Quarto

````markdown
```{r}
#| column: body-outset
#| fig-cap: "Caption"

plot(1:10)
```
````

## Appendices

### distill

````markdown
## Appendix

### Acknowledgments

Thanks to...

### Author Contributions

Author A did...
````

### Quarto

````markdown
## Acknowledgments {.appendix}

Thanks to...

## Author Contributions {.appendix}

Author A did...
````

Or use an appendix section:

````markdown
::: {#appendix}

## Additional Details

More content here.
:::
````

## Code Display

### distill

```yaml
output:
  distill::distill_article:
    code_folding: true
```

### Quarto

```yaml
format:
  html:
    code-fold: true
    code-tools: true
```

## Blog Migration

### distill Blog Structure

```txt
_site.yml
_posts/
  2024-01-01-first-post/
    first-post.Rmd
  2024-01-15-second-post/
    second-post.Rmd
```

### Quarto Blog Structure

```txt
_quarto.yml
posts/
  first-post/
    index.qmd
  second-post/
    index.qmd
```

### Site Configuration

#### Distill (`_site.yml`)

```yaml
name: "My Blog"
title: "My Blog"
navbar:
  right:
    - text: "About"
      href: about.html
```

#### Quarto (`_quarto.yml`)

```yaml
project:
  type: website

website:
  title: "My Blog"
  navbar:
    right:
      - text: "About"
        href: about.qmd

format:
  html:
    theme: cosmo
```

### Blog Listing

- `_quarto.yml`

  ```yaml
  website:
    title: "My Blog"
  ```

- `index.qmd`

  ````markdown
  ---
  title: "My Blog"
  listing:
    contents: posts
    type: default
    sort: "date desc"
  ---
  ````

## Post Front Matter

### distill

```yaml
title: "Post Title"
description: "Brief description"
author:
  - name: "Author Name"
date: 2024-01-15
categories:
  - R
  - Data Science
preview: preview.png
output:
  distill::distill_article:
    self_contained: false
```

### Quarto

```yaml
title: "Post Title"
description: "Brief description"
author: "Author Name"
date: 2024-01-15
categories:
  - R
  - Data Science
image: preview.png
```

## Creative Commons

### distill

```yaml
creative_commons: CC BY
```

### Quarto

```yaml
license: "CC BY"
```

Or more detailed:

```yaml
license:
  type: CC BY
  url: https://creativecommons.org/licenses/by/4.0/
```

## Resources

- [Quarto HTML Documents](https://quarto.org/docs/output-formats/html-basics.html)
- [Quarto Websites](https://quarto.org/docs/websites/)
- [Article Layout](https://quarto.org/docs/authoring/article-layout.html)

# Jupyter Notebook (.ipynb) and Quarto (.qmd) Interoperability

## Direct Rendering

Quarto renders `.ipynb` files without conversion:

```bash
quarto render notebook.ipynb
quarto render notebook.ipynb --to pdf
```

Cell outputs stored in the notebook are used by default.
Set `execute: enabled: true` in YAML front matter to force re-execution.

## Converting Between Formats

`quarto convert` works in both directions:

```bash
quarto convert notebook.ipynb   # → notebook.qmd
quarto convert notebook.qmd     # → notebook.ipynb
```

Converting `.ipynb` → `.qmd` extracts cell source into code blocks, converts markdown cells to prose, and discards stored outputs (Quarto re-executes on next render).

Converting `.qmd` → `.ipynb` produces a notebook matching the `.qmd` structure, without executing cells.

## When to Use Each Format

Prefer `.qmd` for version-controlled documents: plain text produces clean diffs, cell options use hashpipe syntax (`#|`) instead of JSON metadata, and any text editor can be used.

Prefer `.ipynb` for interactive exploration, sharing with users who do not use Quarto, or workflows that rely heavily on Jupyter widgets.

## Resources

- [Quarto convert CLI](https://quarto.org/docs/tools/jupyter-lab.html)
- [Jupyter Kernel Execution](https://quarto.org/docs/computations/jupyter.html)

# Converting R Markdown to Quarto

Guide for converting R Markdown (.Rmd) documents to Quarto (.qmd).

## Overview

Most R Markdown documents can be rendered by Quarto with minimal changes. The main differences are:

1. YAML structure (output → format)
2. Chunk options (inline → hashpipe)
3. Option naming (dots → dashes)

## Quick Start

### Rename File

```bash
mv document.Rmd document.qmd
```

### Update YAML

#### R Markdown

```yaml
output: html_document
````

#### Quarto

```yaml
format: html
```

### Update Chunk Options

#### R Markdown

````markdown
```{r, echo=TRUE, fig.cap="My figure"}
plot(1:10)
```
````

#### Quarto

````markdown
```{r}
#| echo: true
#| fig-cap: "My figure"

plot(1:10)
```
````

## Format Mapping

| R Markdown                | Quarto     |
| ------------------------- | ---------- |
| `html_document`           | `html`     |
| `pdf_document`            | `pdf`      |
| `word_document`           | `docx`     |
| `github_document`         | `gfm`      |
| `beamer_presentation`     | `beamer`   |
| `ioslides_presentation`   | `revealjs` |
| `slidy_presentation`      | `revealjs` |
| `powerpoint_presentation` | `pptx`     |

## YAML Conversion

### Basic Document

#### R Markdown

```yaml
title: "My Document"
author: "Jane Doe"
date: "2024-01-15"
output:
  html_document:
    toc: true
    toc_float: true
    code_folding: show
```

#### Quarto

```yaml
title: "My Document"
author: "Jane Doe"
date: 2024-01-15
format:
  html:
    toc: true
    toc-location: left
    code-fold: show
```

### Multiple Outputs

#### R Markdown

```yaml
output:
  html_document:
    toc: true
  pdf_document:
    toc: true
```

#### Quarto

```yaml
format:
  html:
    toc: true
  pdf:
    toc: true
```

### Common Options

| R Markdown              | Quarto                   |
| ----------------------- | ------------------------ |
| `toc: true`             | `toc: true`              |
| `toc_float: true`       | `toc-location: left`     |
| `toc_depth: 3`          | `toc-depth: 3`           |
| `number_sections: true` | `number-sections: true`  |
| `code_folding: show`    | `code-fold: show`        |
| `theme: cosmo`          | `theme: cosmo`           |
| `highlight: tango`      | `highlight-style: tango` |
| `fig_width: 8`          | `fig-width: 8`           |
| `fig_height: 6`         | `fig-height: 6`          |
| `df_print: kable`       | (use knitr::kable or gt) |

## Chunk Options

### Syntax Change

Options move inside the code block with `#|` prefix:

#### R Markdown

````markdown
```{r my-chunk, echo=FALSE, fig.cap="Caption", fig.width=8}
plot(1:10)
```
````

#### Quarto

````markdown
```{r}
#| label: my-chunk
#| echo: false
#| fig-cap: "Caption"
#| fig-width: 8

plot(1:10)
```
````

### Option Naming: Dots to Dashes

| R Markdown   | Quarto                   |
| ------------ | ------------------------ |
| `fig.cap`    | `fig-cap`                |
| `fig.width`  | `fig-width`              |
| `fig.height` | `fig-height`             |
| `fig.align`  | `fig-align`              |
| `fig.alt`    | `fig-alt`                |
| `out.width`  | (use `fig-width` or CSS) |
| `results`    | `output`                 |
| `message`    | `message`                |
| `warning`    | `warning`                |
| `include`    | `include`                |

### Results Option

#### R Markdown

```yaml
results='asis'
results='hide'
results='markup'
```

#### Quarto

```yaml
#| output: asis
#| output: false
#| output: true
```

## Setup Chunks

### R Markdown

````markdown
```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.width = 8,
  fig.height = 6
)
```
````

### Quarto

Use YAML instead:

```yaml
execute:
  echo: true
  warning: false
  message: false
format:
  html:
    fig-width: 8
    fig-height: 6
```

Or keep setup chunk for R-specific options.

## Inline Code

### R Markdown

````markdown
The value is `r mean(x)`.
````

### Quarto

Same syntax works:

````markdown
The value is `r mean(x)`.
````

Or with explicit language:

````markdown
The value is `{r} mean(x)`.
````

## Cross-References

### Figures

#### R Markdown (requires bookdown)

````markdown
```{r my-fig, fig.cap="Caption"}
plot(1:10)
```

See Figure \@ref(fig:my-fig).
````

#### Quarto

````markdown
```{r}
#| label: fig-myplot
#| fig-cap: "Caption"

plot(1:10)
```

See @fig-myplot.
````

### Tables

#### R Markdown (requires bookdown)

````markdown
```{r my-table}
knitr::kable(mtcars[1:5,], caption = "My table")
```

See Table \@ref(tab:my-table).
````

#### Quarto

````markdown
```{r}
#| label: tbl-mydata
#| tbl-cap: "My table"

knitr::kable(mtcars[1:5,])
```

See @tbl-mydata.
````

Note: Quarto uses `tbl-` prefix (not `tab-`).

## Package Dependencies

Quarto doesn't require `rmarkdown` or `knitr`, but `knitr` remains useful for tables and chunk processing. Most R Markdown features (`knitr::kable()`, `knitr::include_graphics()`) work in Quarto without changes.

Note: Quarto can render `.Rmd` files directly (`quarto render document.Rmd`) using R Markdown compatibility mode, which allows incremental migration.

## Common Issues

### Output Not Found

```txt
ERROR: Unknown format
```

Check format name mapping (e.g., `html_document` → `html`).

### Figure Not Appearing

Ensure label starts with `fig-` for cross-references.

### Table Cross-Reference Fails

Use `tbl-` prefix (not `tab-`).

### Chunk Options Ignored

Verify `#|` syntax and dashes (not dots).

## Resources

- [Quarto for R Markdown Users](https://quarto.org/docs/faq/rmarkdown.html)
- [Quarto vs R Markdown](https://quarto.org/docs/faq/rmarkdown.html#quarto-vs.-r-markdown)

# Converting xaringan to Quarto RevealJS

Guide for converting xaringan presentations to Quarto RevealJS format.

## Overview

Key differences:

1. Format: `moon_reader` → `revealjs`
2. Slide separators: `---` → headers
3. Incremental: `--` → `::: {.incremental}`
4. Speaker notes: `???` → `::: {.notes}`

## Quick Start

### 1. Rename File

```bash
mv slides.Rmd slides.qmd
```

### 2. Update YAML

#### Xaringan

```yaml
output:
  xaringan::moon_reader:
    lib_dir: libs
    nature:
      highlightStyle: github
```

#### Quarto

```yaml
format:
  revealjs:
    theme: default
    highlight-style: github
```

### 3. Convert Slides

Replace `---` with headers:

````markdown
# xaringan

---

# Slide Title

Content

---

# Next Slide

# Quarto

## Slide Title

Content

## Next Slide
````

## YAML Conversion

### Basic Presentation

#### Xaringan

```yaml
title: "My Presentation"
author: "Jane Doe"
date: "2024-01-15"
output:
  xaringan::moon_reader:
    css: ["default", "custom.css"]
    nature:
      ratio: "16:9"
      highlightStyle: github
      highlightLines: true
      countIncrementalSlides: false
```

#### Quarto

```yaml
title: "My Presentation"
author: "Jane Doe"
date: 2024-01-15
format:
  revealjs:
    theme: default
    css: custom.css
    slide-number: true
    highlight-style: github
    code-line-numbers: true
    width: 1600
    height: 900
```

### Common Options

| xaringan                 | Quarto RevealJS                       |
| ------------------------ | ------------------------------------- |
| `ratio: "16:9"`          | `width: 1600` / `height: 900`         |
| `highlightStyle: github` | `highlight-style: github`             |
| `highlightLines: true`   | `code-line-numbers: true`             |
| `countdown`              | `chalkboard: true` or timer extension |
| `autoplay: 30000`        | `auto-slide: 30000`                   |

## Slide Separators

### xaringan

Uses `---` to separate slides:

````markdown
# First Slide

Content

---

# Second Slide

More content

---

class: center, middle

# Centered Slide
````

### Quarto

Uses headers (level 1 or 2):

````markdown
# First Slide

Content

## Second Slide

More content

## Centered Slide {.center}
````

Or with explicit separators:

```yaml
format:
  revealjs:
    slide-level: 2
```

## Incremental Reveals

### xaringan

Uses `--` within a slide:

````markdown
# Incremental

- ## First point

- ## Second point

- Third point
````

### Quarto

Use incremental class:

````markdown
## Incremental

::: {.incremental}

- First point
- Second point
- Third point

:::
````

Or globally:

```yaml
format:
  revealjs:
    incremental: true
```

Per-slide opt-out:

````markdown
## Non-Incremental {.nonincremental}

- All at once
- All at once
````

## Speaker Notes

### xaringan

Uses `???`:

````markdown
# Slide Title

Content here.

???

Speaker notes go here.
They can span multiple lines.
````

### Quarto

Uses notes div:

````markdown
## Slide Title

Content here.

::: {.notes}
Speaker notes go here.
They can span multiple lines.
:::
````

## Two-Column Layouts

### xaringan

````markdown
.pull-left[
Left content
]

.pull-right[
Right content
]
````

### Quarto

````markdown
::: {.columns}

::: {.column width="50%"}
Left content
:::

::: {.column width="50%"}
Right content
:::

:::
````

## Slide Classes

### xaringan

````markdown
---

class: inverse, center, middle

# Dark Slide
````

### Quarto

````markdown
## Dark Slide {.inverse .center .middle}

Or use theme variants.
````

Background options:

````markdown
## Slide with Background {background-color="black"}
````

## Code Highlighting

### xaringan

````markdown
```{r, highlight.output=c(1,3)}
# Highlighted output
```
````

### Quarto

````markdown
```{r}
#| code-line-numbers: "1,3"

# Highlighted lines
```
````

Or in output:

````markdown
```{r}
#| output-line-numbers: "1,3"
```
````

## CSS Customization

### xaringan

```yaml
output:
  xaringan::moon_reader:
    css: ["default", "my-theme.css"]
```

### Quarto

```yaml
format:
  revealjs:
    theme: [default, custom.scss]
    css: styles.css
```

### Custom SCSS

```scss
// custom.scss
$body-bg: #f0f0f0;
$body-color: #333;
$link-color: #007bff;

.reveal h1 {
  color: navy;
}
```

## Fragments (Animations)

### xaringan

````markdown
.animated.fadeIn[
Content fades in
]
````

### Quarto

````markdown
::: {.fragment .fade-in}
Content fades in
:::
````

Fragment types:

- `.fade-in`
- `.fade-out`
- `.fade-up`
- `.highlight-red`
- `.strike`

## Images and Figures

### xaringan

````markdown
![](image.png)

.center[
![](centered.png)
]
````

### Quarto

````markdown
![](image.png)

![](centered.png){fig-align="center"}
````

### Full-Screen Background

````markdown
## {background-image="image.jpg" background-size="cover"}

Content overlaid on image.
````

## Special Slides

### Title Slide

Automatic in Quarto from YAML.

### Section Headers

````markdown
# Section Title {.section}
````

### Thank You Slide

````markdown
## Thank You! {.center .middle}

Questions?
````

## Common xaringan Features

### Countdown Timer

Install extension:

```bash
quarto add gadenbuie/countdown
```

### Chalkboard

```yaml
format:
  revealjs:
    chalkboard: true
```

### Self-Contained

```yaml
format:
  revealjs:
    embed-resources: true
```

## Resources

- [Quarto RevealJS](https://quarto.org/docs/presentations/revealjs/)
- [RevealJS Options](https://quarto.org/docs/reference/formats/presentations/revealjs.html)
- [Presentation Features](https://quarto.org/docs/presentations/)

# Cross-References

Quarto provides a unified cross-reference system for figures, tables, equations, sections, theorems, and more.

## Label Prefix System

All cross-referenceable elements require a label starting with a type prefix:

| Type              | Prefix | Example Label    | Reference         |
| ----------------- | ------ | ---------------- | ----------------- |
| Figure            | `fig-` | `fig-plot`       | `@fig-plot`       |
| Table             | `tbl-` | `tbl-data`       | `@tbl-data`       |
| Section           | `sec-` | `sec-intro`      | `@sec-intro`      |
| Equation          | `eq-`  | `eq-model`       | `@eq-model`       |
| Theorem           | `thm-` | `thm-main`       | `@thm-main`       |
| Lemma             | `lem-` | `lem-helper`     | `@lem-helper`     |
| Corollary         | `cor-` | `cor-result`     | `@cor-result`     |
| Proposition       | `prp-` | `prp-statement`  | `@prp-statement`  |
| Conjecture        | `cnj-` | `cnj-hypothesis` | `@cnj-hypothesis` |
| Definition        | `def-` | `def-term`       | `@def-term`       |
| Example           | `exm-` | `exm-case`       | `@exm-case`       |
| Exercise          | `exr-` | `exr-problem`    | `@exr-problem`    |
| Listing           | `lst-` | `lst-code`       | `@lst-code`       |
| Note callout      | `nte-` | `nte-info`       | `@nte-info`       |
| Tip callout       | `tip-` | `tip-hint`       | `@tip-hint`       |
| Warning callout   | `wrn-` | `wrn-alert`      | `@wrn-alert`      |
| Important callout | `imp-` | `imp-key`        | `@imp-key`        |
| Caution callout   | `cau-` | `cau-danger`     | `@cau-danger`     |

## Recommended Syntax

For consistency, prefer using div syntax for cross-referenceable elements:

```markdown
::: {#tbl-example}

| Column 1 | Column 2 |
| -------- | -------- |
| Data     | Data     |

Table caption.
:::
```

Instead of inline caption syntax:

```markdown
| Column 1 | Column 2 |
| -------- | -------- |
| Data     | Data     |

: Table caption. {#tbl-example}
```

Both syntaxes work, but div syntax provides a more consistent pattern across all element types (figures, tables, theorems, etc.).

## Reference Syntax

Use `@` followed by the label to create a reference:

```markdown
See @fig-plot for the visualization.
The data is shown in @tbl-results.
As discussed in @sec-methods, we used...
```

### Capitalization

Use capital letter to get capitalized prefix:

```markdown
@fig-plot → Figure 1
@Fig-plot → Figure 1 (same, but ensures capital)
```

### Prefix Customization

Use square brackets for custom prefix:

```markdown
[Figure @fig-plot] → Figure 1
[See @fig-plot] → See 1
[-@fig-plot] → 1 (number only)
```

### Multiple References

```markdown
See @fig-plot and @fig-scatter.
Tables [-@tbl-one; -@tbl-two] show...
```

## Figures

### Code-Generated Figures

````markdown
```{language}
#| label: fig-scatter
#| fig-cap: "Scatter plot of x versus y."

# code that produces a figure
```
````

Reference: `See @fig-scatter.`

### Markdown Figures

```markdown
![Elephant](elephant.png){#fig-elephant}

See @fig-elephant for the image.
```

### Subfigures

```markdown
::: {#fig-animals layout-ncol=2}

![Cat](cat.png){#fig-cat}

![Dog](dog.png){#fig-dog}

Comparison of animals.
:::

See @fig-animals, specifically @fig-cat.
```

## Tables

### Code-Generated Tables

````markdown
```{language}
#| label: tbl-summary
#| tbl-cap: "Summary statistics."

# code that produces a table
```

Reference: `See @tbl-summary.`
````

### Markdown Tables

```markdown
::: {#tbl-data}

| Col 1 | Col 2 |
| ----- | ----- |
| A     | B     |

Summary data.
:::

See @tbl-data for details.
```

### Subtables

```markdown
::: {#tbl-panel layout-ncol=2}

::: {#tbl-first}

| Col A |
| ----- |
| 1     |

First table.
:::

::: {#tbl-second}

| Col B |
| ----- |
| 2     |

Second table.
:::

Combined tables.
:::

See @tbl-panel, including @tbl-first.
```

## Sections

Enable numbered sections to reference them:

```yaml
number-sections: true
```

Add label to heading:

```markdown
## Introduction {#sec-intro}

As discussed in @sec-intro...
```

## Equations

```markdown
$$
y = mx + b
$$ {#eq-line}

Equation @eq-line shows...
$$
```

## Theorems and Proofs

```markdown
::: {#thm-pythagorean}

## Pythagorean Theorem

For a right triangle with legs $a$ and $b$ and hypotenuse $c$:
$$a^2 + b^2 = c^2$$
:::

By @thm-pythagorean, we know...
```

Available theorem types: `thm`, `lem`, `cor`, `prp`, `cnj`, `def`, `exm`, `exr`.

## Code Listings

````markdown
```{#lst-example .python lst-cap="Example Python code"}
def hello():
    print("Hello, world!")
```

See @lst-example for the code.
````

## Callouts

Make callouts cross-referenceable by adding an ID:

```markdown
::: {#nte-important .callout-note}

## Important Note

This is cross-referenceable.
:::

See @nte-important for details.
```

## Custom Cross-Reference Types

Define custom types in YAML:

```yaml
crossref:
  custom:
    - kind: float
      key: vid
      reference-prefix: "Video"
      caption-prefix: "Video"
```

Use:

```markdown
::: {#vid-demo}
<video src="demo.mp4"></video>

Demo video.
:::

See @vid-demo.
```

## Cross-Reference Options

Configure in YAML front matter:

```yaml
crossref:
  fig-title: "Figure" # Prefix for figures
  tbl-title: "Table" # Prefix for tables
  eq-prefix: "Equation" # Prefix for equations
  sec-prefix: "Section" # Prefix for sections
  fig-prefix: "Figure" # In-text prefix
  tbl-prefix: "Table" # In-text prefix
  chapters: true # Number by chapter
```

### Localization

```yaml
lang: de
crossref:
  fig-title: "Abbildung"
  tbl-title: "Tabelle"
```

For bookdown migration details, see [conversion-bookdown.md](conversion-bookdown.md).

## Resources

- [Quarto Cross-References](https://quarto.org/docs/authoring/cross-references.html)
- [Figures](https://quarto.org/docs/authoring/figures.html)
- [Tables](https://quarto.org/docs/authoring/tables.html)

# Diagrams

Quarto natively supports Mermaid and Graphviz diagrams, rendering them automatically across output formats.

## Mermaid Diagrams

Mermaid is a JavaScript-based diagramming tool using text definitions.

### Basic Syntax

````markdown
```{mermaid}
flowchart LR
  A[Start] --> B[Process]
  B --> C[End]
```
````

### Flowcharts

````markdown
```{mermaid}
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```
````

Direction options: `TB` (top-bottom), `TD` (top-down), `BT`, `RL`, `LR`.

All standard Mermaid diagram types are supported: `sequenceDiagram`, `classDiagram`, `stateDiagram-v2`, `erDiagram`, `gantt`, `pie`, etc. Use standard Mermaid syntax inside `{mermaid}` code cells.

## Mermaid Cell Options

Use `%%|` for options:

````markdown
```{mermaid}
%%| label: fig-flowchart
%%| fig-cap: "Process flowchart."

flowchart LR
  A --> B --> C
```
````

### Common Options

| Option           | Description        | Example         |
| ---------------- | ------------------ | --------------- |
| `label`          | Cross-reference ID | `fig-diagram`   |
| `fig-cap`        | Caption            | `"My diagram."` |
| `fig-width`      | Width              | `6` (inches)    |
| `fig-height`     | Height             | `4` (inches)    |
| `fig-responsive` | Responsive sizing  | `true`, `false` |

### External File

````markdown
```{mermaid}
%%| file: diagram.mmd
```
````

## Graphviz/DOT Diagrams

Graphviz uses DOT language for graph descriptions.

### Basic Syntax

````markdown
```{dot}
digraph G {
  A -> B -> C;
  B -> D;
}
```
````

Use `digraph` for directed graphs, `graph` for undirected. Standard DOT features (subgraphs, node styling, rank direction) all work.

## Graphviz Cell Options

Use `//|` for options:

````markdown
```{dot}
//| label: fig-graph
//| fig-cap: "Network diagram."

digraph {
  A -> B -> C;
}
```
````

### External File

````markdown
```{dot}
//| file: network.dot
```
````

## Cross-Referencing Diagrams

Both Mermaid and Graphviz diagrams can be cross-referenced:

````markdown
```{mermaid}
%%| label: fig-process
%%| fig-cap: "The data processing workflow."

flowchart LR
  Input --> Process --> Output
```

See @fig-process for the workflow.
````

## Sizing

Use `%%| fig-width` and `%%| fig-height` cell options. Diagrams are responsive by default in HTML; disable with `%%| fig-responsive: false`.

## Theming

### Mermaid Themes

Configure Mermaid theming using a YAML block inside the code cell:

````markdown
```{mermaid}
---
config:
  theme: forest
---

flowchart LR
  A --> B
```
````

Available themes: `default`, `forest`, `dark`, `neutral`, `base`.

### Custom Theme Variables

````markdown
```{mermaid}
---
config:
  theme: base
  themeVariables:
    primaryColor: "#f0f0f0"
    primaryBorderColor: "#333"
    fontFamily: "Fira Code, monospace"
---

flowchart LR
  A --> B
```
````

### Theming and Render Format

When using `mermaid-format: js` (the default for HTML), Quarto controls theming and may override custom theme configurations.
The YAML config block inside the Mermaid cell might appear to have no effect.

To ensure custom theming works:

1. Use native Quarto theming options in document YAML.
2. Change to `mermaid-format: svg` or `mermaid-format: png`.

```yaml
format:
  html:
    mermaid:
      theme: forest
```

Or use a different render format:

```yaml
format:
  html:
    mermaid-format: svg
```

With `svg` or `png` format, the YAML config block inside Mermaid cells will be respected.

### CSS Customization

For additional styling in HTML:

```css
:root {
  --mermaid-font-family: "Fira Code", monospace;
}
```

### Graphviz Styling

Use DOT attributes:

````markdown
```{dot}
digraph {
  bgcolor="transparent";
  node [fontname="Helvetica", fontsize=12];
  edge [color=gray];

  A -> B;
}
```
````

## Rendering

### HTML Output

Diagrams rendered with JavaScript (Mermaid) or as SVG (Graphviz).

### PDF/DOCX Output

Rendered as images using Chrome/Chromium.

Requires Chrome or Edge installed, or set:

```yaml
mermaid:
  puppeteer:
    executablePath: /path/to/chrome
```

## Diagram in Figures

Combine with figure elements:

````markdown
::: {#fig-workflow}

```{mermaid}
flowchart TD
  A --> B --> C
```

Complete workflow diagram.
:::

````

## Tips

### Complex Diagrams

For complex diagrams, use external files:

````markdown
```{mermaid}
%%| file: complex-diagram.mmd
%%| fig-cap: "Complex system architecture."
```

````

### Accessibility

Add alt text:

````markdown
```{mermaid}
%%| fig-alt: "Flowchart showing three sequential steps."

flowchart LR
  A --> B --> C
```
````

## Resources

- [Quarto Diagrams](https://quarto.org/docs/authoring/diagrams.html)
- [Mermaid Documentation](https://mermaid.js.org/)
- [Graphviz Documentation](https://graphviz.org/documentation/)
- [DOT Language](https://graphviz.org/doc/info/lang.html)

# Divs and Spans

Divs and spans are Pandoc's fenced syntax for applying classes, IDs, and attributes to blocks and inline content.

## Fenced Divs

### Basic Syntax

````markdown
::: {.class-name}
Content inside the div.
:::
````

Three colons open, three colons close.

### Multiple Classes

````markdown
::: {.class1 .class2}
Content with multiple classes.
:::
````

### With ID

````markdown
::: {#my-id .my-class}
Content with ID and class.
:::
````

### With Attributes

````markdown
::: {.my-class key="value" data-info="something"}
Content with attributes.
:::
````

## Nested Divs

Nest divs inside each other:

````markdown
::: {.outer}
Outer content.

::: {.inner}
Inner content.
:::

More outer content.
:::
````

Or use different numbers:

````markdown
::: {.level1}
::: {.level2}
::: {.level3}
Deeply nested.
:::
:::
:::
````

## Spans

### Basic Syntax

````markdown
This is [styled text]{.highlight}.
````

### Multiple Classes

````markdown
[Important]{.bold .red}
````

### With ID

````markdown
[Target text]{#target-id}
````

### With Attributes

````markdown
[Text]{.class key="value"}
````

## Common Div Uses

### Custom Styling

````markdown
::: {.callout-box}
Important information here.
:::
````

With CSS:

```css
.callout-box {
  background: #f0f0f0;
  padding: 1em;
  border-left: 4px solid #007bff;
}
```

### Columns

````markdown
::: {.columns}

::: {.column width="50%"}
Left column.
:::

::: {.column width="50%"}
Right column.
:::

:::
````

### Centering

````markdown
::: {.center}
Centered content.
:::
````

### Hiding Content

````markdown
::: {.hidden}
This won't appear.
:::
````

## Raw Content Blocks

Insert format-specific content:

### HTML

````markdown
```{=html}
<div class="custom-html">
  <p>Raw HTML content.</p>
</div>
```
````

### LaTeX

````markdown
```{=latex}
\begin{center}
Raw LaTeX content.
\end{center}
```
````

### Typst

````markdown
```{=typst}
#align(center)[
  Raw Typst content.
]
```
````

### Inline Raw Content

````markdown
Text with `<br>`{=html} line break.
````

## Layout Divs

### Tabsets

````markdown
::: {.panel-tabset}

## Tab 1

Tab 1 content.

## Tab 2

Tab 2 content.

:::
````

### Columns with Layout

````markdown
::: {layout-ncol=2}
![](image1.png)

![](image2.png)
:::
````

### Complex Layout

````markdown
::: {layout="[[1,1], [1]]"}
First cell.

Second cell.

Full-width cell.
:::
````

## Conditional Divs

### Format-Specific

````markdown
::: {.content-visible when-format="html"}
HTML-only content.
:::
````

### Hidden for Format

````markdown
::: {.content-hidden when-format="pdf"}
Hidden in PDF.
:::
````

## Special Divs

### Callouts

````markdown
::: {.callout-note}
Note content.
:::
````

### Cross-Referenceable

````markdown
::: {#fig-diagram}
![](diagram.png)

Figure caption.
:::
````

### Theorems

````markdown
::: {#thm-main}
Theorem statement.
:::
````

### Proof

````markdown
::: {.proof}
Proof content.
:::
````

## Span Uses

### Inline Styling

````markdown
This is [red text]{style="color: red;"}.
````

### Class Application

````markdown
The [key term]{.term} is defined as...
````

### Small Caps

````markdown
[Small Caps Text]{.smallcaps}
````

### Underline

````markdown
[Underlined text]{.underline}
````

### Keyboard Input

````markdown
Press [Ctrl]{.kbd}+[C]{.kbd} to copy.
````

Custom CSS classes defined in your stylesheet can be applied via `.class` on divs/spans. Common attributes: `.class`, `#id`, `style="..."`, `width`, `height`, `data-*`.

## Format-Specific Considerations

### HTML

Full CSS styling support. All classes and attributes render directly.

### PDF (LaTeX)

Limited styling. Some classes map to LaTeX commands:

- `.unnumbered` - Removes section numbering
- `.unlisted` - Excludes from TOC

### Word (DOCX)

Classes can map to Word styles via reference doc.

### RevealJS

Special classes:

- `.fragment` - Incremental reveal
- `.notes` - Speaker notes
- `.r-fit-text` - Auto-fit text

## Resources

- [Pandoc Divs and Spans](https://pandoc.org/MANUAL.html#divs-and-spans)
- [Quarto Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html)

# Compute Engines

Quarto separates the authoring layer (YAML front matter, hashpipe options, cross-references, layouts) from the compute engine that executes code cells.
All cell options, figure/table options, and cross-reference syntax are identical across engines.

## Engine Overview

| Engine    | Activated by                          | Primary language(s) | Notes                                               |
| --------- | ------------------------------------- | ------------------- | --------------------------------------------------- |
| `knitr`   | `{r}` cells                           | R                   | Default when R cells are present                    |
| `julia`   | `{julia}` cells                       | Julia               | Default when Julia cells are present (Quarto 1.9+)  |
| `jupyter` | `{python}` or any Jupyter kernel cell | Python, others      | Default for Python and other non-R, non-Julia cells |

Since Quarto 1.9, engine extensions allow third-party engines to register additional language identifiers.
The `{LANGUAGE}` cell surface and all hashpipe options remain the same regardless of the engine.

## Auto-Detection

Quarto picks the engine automatically from the first executable cell in the document:

- First `{r}` cell → knitr engine.
- First `{julia}` cell → julia engine (Quarto 1.9+).
- First `{python}` or other non-R, non-Julia cell → jupyter engine.

## Selecting an Engine Explicitly

Override auto-detection in YAML front matter:

```yaml
engine: knitr
```

```yaml
engine: jupyter
jupyter: python3 # kernel name (default: python3)
```

```yaml
engine: julia
```

The `jupyter` key accepts any installed kernel name:

```yaml
engine: jupyter
jupyter: ir        # R via IRkernel
jupyter: myenv     # named conda/venv kernel
jupyter: julia-1.10
```

List available kernels with:

```bash
jupyter kernelspec list
```

## Hashpipe Comment Prefix

The hashpipe comment prefix depends on the cell type:

- R, Python, Julia: `#|`
- Mermaid: `%%|`
- Graphviz/DOT: `//|`

## Engine-Specific Behaviour

### Table Output

**knitr engine**: Values returned from a cell that are recognised as table objects (e.g. data frames, matrices) are automatically rendered as markdown tables.

**jupyter engine**: Cells returning a display-protocol object auto-display as HTML in HTML output only.
For portable output across all formats, print a markdown string and use `output: asis`:

````markdown
```{language}
#| tbl-cap: "Summary statistics."
#| output: asis

# print markdown table string to stdout
```
````

### Inline Code

Inline code syntax differs by engine:

| Engine  | Inline syntax                                             |
| ------- | --------------------------------------------------------- |
| knitr   | `` `r expr` ``                                            |
| jupyter | Not supported natively in `.qmd`; use cell output instead |
| julia   | Not supported natively in `.qmd`; use cell output instead |

### Caching

Both knitr and jupyter engines support cell-level caching with `cache: true`.
For project-level freeze (skip re-execution when source is unchanged):

```yaml
execute:
  freeze: auto
```

## Engine Extensions (Quarto 1.9+)

Third-party extensions can register custom engines via the Quarto extension system.
Custom engines use the same `{LANGUAGE}` cell syntax and the same `#|` hashpipe options as built-in engines.
Install engine extensions with:

```bash
quarto add <extension>
```

Then activate in YAML:

```yaml
engine: <extension-engine-name>
```

## Resources

- [Using R](https://quarto.org/docs/computations/r.html)
- [Using Python](https://quarto.org/docs/computations/python.html)
- [Using Julia](https://quarto.org/docs/computations/julia.html)
- [Execution Options](https://quarto.org/docs/computations/execution-options.html)
- [Engine Extensions](https://quarto.org/docs/extensions/engine.html)

# Extensions

Quarto extensions add custom functionality including shortcodes, filters, formats, and RevealJS plugins.

## Extension Types

| Type             | Description                               |
| ---------------- | ----------------------------------------- |
| Shortcodes       | Custom `{{< shortcode >}}` commands       |
| Filters          | Pandoc filters for content transformation |
| Formats          | Custom output formats                     |
| RevealJS Plugins | Presentation enhancements                 |

## Finding Extensions

### Official Repository

- [Quarto Extensions](https://quarto.org/docs/extensions/)
- Browse by category: filters, shortcodes, formats, etc.

### Community Extensions

- [Community Extensions List](https://m.canouil.dev/quarto-extensions/)
- [Extensions JSON](https://m.canouil.dev/quarto-extensions/extensions.json)
- Search GitHub for `quarto-extension`

## Installing Extensions

### Basic Installation

```bash
quarto add username/repository
```

### From GitHub

```bash
quarto add quarto-ext/fontawesome
quarto add shafayetShafee/bsicons
```

### Specific Version

```bash
quarto add username/repository@v1.0.0
```

### From URL

```bash
quarto add https://github.com/user/repo/archive/main.zip
```

### Interactive Installation

When prompted, confirm trust in the extension source.

## Using Extensions

### In Document YAML

```yaml
---
filters:
  - extension-name
---
```

### Shortcode Extensions

After installing, use in document:

````markdown
{{< fa brands github >}} # Font Awesome icon
````

### Format Extensions

```yaml
format: custom-format
```

## Managing Extensions

### Location

Extensions are stored in `_extensions/` directory:

```txt
project/
├── _extensions/
│   └── fontawesome/
│       ├── _extension.yml
│       └── fontawesome.lua
├── document.qmd
└── _quarto.yml
```

### List Installed Extensions

```bash
ls _extensions/
```

### Update Extensions

```bash
quarto add username/repository  # Re-run to update
```

### Remove Extensions

Delete the folder from `_extensions/`:

```bash
rm -rf _extensions/extension-name
```

## Project vs Document Extensions

### Project-Wide

Install in project root. Available to all documents:

```txt
project/
├── _extensions/
├── chapter1.qmd
└── chapter2.qmd
```

### Global Extensions

Install in user config (less common):

```bash
quarto add --global username/repository
```

Location: `~/.local/share/quarto/extensions/`

## Popular Extensions

### Icons

```bash
quarto add quarto-ext/fontawesome
```

````markdown
{{< fa brands github >}} GitHub
{{< fa solid envelope >}} Email
````

### Lightbox

```bash
quarto add quarto-ext/lightbox
```

```yaml
lightbox: true
```

### Include Code from Files

```bash
quarto add quarto-ext/include-code-files
```

````markdown
{{< include-code example.py >}}
````

### Fancy Text

```bash
quarto add quarto-ext/fancy-text
```

````markdown
{{< lipsum 1 >}}
````

### Social Cards

```bash
quarto add gadenbuie/quarto-social-embeds
```

````markdown
{{< tweet user=username id=123456789 >}}
````

## Extension Configuration

Some extensions have configuration options:

```yaml
lightbox:
  match: auto
  effect: zoom
  loop: true

fontawesome:
  version: 6
```

## Creating Custom Extensions

### Basic Structure

```txt
_extensions/
└── my-extension/
    ├── _extension.yml
    └── my-extension.lua
```

### Extension YAML

In `_extension.yml`:

```yaml
title: My Extension
author: Your Name
version: 1.0.0
contributes:
  shortcodes:
    - my-extension.lua
```

### Shortcode Lua

In `my-extension.lua`:

```lua
return {
  ['my-shortcode'] = function(args)
    local text = args[1] or "default"
    return pandoc.Str("Processed: " .. text)
  end
}
```

### Use

````markdown
{{< my-shortcode "Hello" >}}
````

## Troubleshooting

### Extension Not Found

```txt
ERROR: Extension not found
```

- Check extension is in `_extensions/`
- Verify extension name matches folder

### Trust Warning

When installing, Quarto asks about trust. Extensions run code during render.

### Conflicts

If extensions conflict, try:

1. Check extension documentation for compatibility
2. Update extensions to latest versions
3. Report issue to extension maintainer

## Extension Sources

### GitHub Organizations

- `quarto-ext` - Official Quarto extensions
- `quarto-journals` - Academic journal formats

### Popular Repositories

| Extension                       | Description           |
| ------------------------------- | --------------------- |
| `quarto-ext/fontawesome`        | Font Awesome icons    |
| `quarto-ext/lightbox`           | Image lightbox        |
| `quarto-ext/include-code-files` | Include external code |
| `shafayetShafee/bsicons`        | Bootstrap icons       |
| `mcanouil/quarto-letter`        | Letter format         |
| `jmbuhr/quarto-molstar`         | Molecular viewer      |

## Best Practices

### Before Installing

1. Check extension source is trustworthy
2. Read the documentation
3. Check compatibility with your Quarto version

### In Projects

1. Document which extensions are used
2. Include `_extensions/` in version control
3. Pin versions for reproducibility

### Updating

1. Test updates in development first
2. Check changelogs for breaking changes
3. Update one at a time

## Resources

- [Quarto Extensions Guide](https://quarto.org/docs/extensions/)
- [Creating Extensions](https://quarto.org/docs/extensions/creating.html)
- [Community Extensions](https://m.canouil.dev/quarto-extensions/)
- [Extensions JSON API](https://m.canouil.dev/quarto-extensions/extensions.json)

# Figures

Quarto provides comprehensive support for figures including sizing, layout, subfigures, and accessibility features.

## Basic Figure Syntax

### Markdown Images

```markdown
![Caption text](image.png)
```

### With Attributes

```markdown
![Caption text](image.png){width=50%}
```

### Cross-Referenceable Figure

```markdown
![Caption text](image.png){#fig-example}

See @fig-example.
```

## Figure Attributes

Common attributes for images:

| Attribute   | Description  | Example                  |
| ----------- | ------------ | ------------------------ |
| `width`     | Image width  | `width=50%`, `width=4in` |
| `height`    | Image height | `height=3in`             |
| `fig-align` | Alignment    | `fig-align="center"`     |
| `fig-alt`   | Alt text     | `fig-alt="Description"`  |

### Sizing

Multiple units supported:

```markdown
![](image.png){width=50%}
![](image.png){width=400px}
![](image.png){width=4in}
![](image.png){width=10cm}
```

### Alignment

```markdown
![Left aligned](image.png){fig-align="left"}
![Centered](image.png){fig-align="center"}
![Right aligned](image.png){fig-align="right"}
```

### Alt Text for Accessibility

```markdown
![Caption](image.png){fig-alt="Detailed description for screen readers"}
```

Alt text differs from caption - it describes the image content for accessibility.

## Computational Figures

Figures generated from code use hashpipe options:

````markdown
```{language}
#| label: fig-scatter
#| fig-cap: "Scatter plot showing the relationship."
#| fig-alt: "Scatter plot with positive trend."
#| fig-width: 8
#| fig-height: 6
#| fig-align: center

# code that produces a figure
```
````

### Figure Options

| Option             | Description      | Example                         |
| ------------------ | ---------------- | ------------------------------- |
| `fig-cap`          | Caption          | `"Figure caption."`             |
| `fig-subcap`       | Subcaptions      | `["A", "B"]`                    |
| `fig-alt`          | Alt text         | `"Description."`                |
| `fig-width`        | Width in inches  | `8`                             |
| `fig-height`       | Height in inches | `6`                             |
| `fig-align`        | Alignment        | `"center"`                      |
| `fig-cap-location` | Caption position | `"bottom"`, `"top"`, `"margin"` |
| `fig-format`       | Output format    | `"png"`, `"svg"`, `"pdf"`       |
| `fig-dpi`          | Resolution       | `300`                           |

## Subfigures

Group multiple images with a shared caption:

```markdown
::: {#fig-comparison layout-ncol=2}

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

![Second image](image2.png){#fig-second}

Comparison of two approaches.
:::

See @fig-comparison, particularly @fig-first.
```

### From Code

````markdown
```{language}
#| label: fig-panels
#| fig-cap: "Panel figure."
#| fig-subcap:
#|   - "Distribution of X"
#|   - "Distribution of Y"
#| layout-ncol: 2

# code that produces two figures (one per panel)
```
````

## Figure Layouts

For arranging multiple figures, use layout divs. See [layout.md](layout.md) for full layout options.

### Basic Layout

```markdown
::: {layout-ncol=2}
![](image1.png)

![](image2.png)
:::
```

### Layout Attributes

| Attribute       | Description         | Example             |
| --------------- | ------------------- | ------------------- |
| `layout-ncol`   | Number of columns   | `layout-ncol=2`     |
| `layout-nrow`   | Number of rows      | `layout-nrow=2`     |
| `layout`        | Custom layout array | `layout="[[1,1]]"`  |
| `layout-valign` | Vertical alignment  | `layout-valign=top` |

## Figure Panels

For images without individual captions:

```markdown
::: {#fig-panel layout-ncol=2}
![](plot1.png)

![](plot2.png)

Multiple plots in a panel.
:::
```

## Caption Location

### Document Level

```yaml
fig-cap-location: top
```

### Per Figure

````markdown
```{language}
#| label: fig-example
#| fig-cap: "Caption on top."
#| fig-cap-location: top

# code that produces a figure
```
````

Options: `top`, `bottom`, `margin`.

## Lightbox

Enable click-to-zoom for images (HTML only):

```markdown
![](image.png){.lightbox}
```

Or for a group:

```markdown
::: {.lightbox}
![](image1.png)

![](image2.png)
:::
```

### Lightbox Options

```markdown
![](image.png){.lightbox group="gallery" description="Detailed view"}
```

### Enable Globally

```yaml
lightbox: true
```

Or with options:

```yaml
lightbox:
  match: auto
  effect: zoom
  loop: true
```

## Linked Images

Make images clickable:

```markdown
[![Caption](thumbnail.png)](fullsize.png)
```

Or link to URL:

```markdown
[![Logo](logo.png)](https://example.com)
```

## Figure Divs

For complex figure content:

```markdown
::: {#fig-custom}

<iframe src="interactive.html"></iframe>

Custom interactive figure.
:::
```

## Document Defaults

Set figure defaults in YAML:

```yaml
format:
  html:
    fig-width: 8
    fig-height: 6
    fig-format: svg
    fig-dpi: 300
    fig-align: center
```

## Resources

- [Quarto Figures](https://quarto.org/docs/authoring/figures.html)
- [Figure Layout](https://quarto.org/docs/authoring/figures.html#figure-panels)
- [Lightbox](https://quarto.org/docs/output-formats/html-lightbox-figures.html)

# Layout

Quarto provides column classes for controlling content width and placement, including margin content.

## Column Classes

### Available Columns

| Class                  | Description                     |
| ---------------------- | ------------------------------- |
| `.column-body`         | Default body width              |
| `.column-body-outset`  | Slightly wider than body        |
| `.column-page`         | Page width (narrower than full) |
| `.column-page-inset`   | Page width with inset           |
| `.column-screen`       | Full screen width               |
| `.column-screen-inset` | Screen width with margins       |
| `.column-margin`       | Right margin                    |

### Body Column (Default)

Standard content width:

```markdown
::: {.column-body}
Default body-width content.
:::
```

### Body Outset

Slightly wider than body:

```markdown
::: {.column-body-outset}
![Wide image](wide.png)
:::
```

### Page Width

Extends to page margins:

```markdown
::: {.column-page}
![Page-width image](panorama.png)
:::
```

### Screen Width

Full browser width (no margins):

```markdown
::: {.column-screen}
![Full-width image](banner.png)
:::
```

### Screen Inset

Full width with small margins:

```markdown
::: {.column-screen-inset}
Content with small margins.
:::
```

### Shaded Screen Inset

With background shading:

```markdown
::: {.column-screen-inset-shaded}
Shaded full-width content.
:::
```

## Directional Variants

Each column class has left/right variants:

```markdown
::: {.column-body-outset-left}
Extends left only.
:::

::: {.column-page-right}
Extends to right page margin.
:::

::: {.column-screen-left}
Full width on left side.
:::
```

## Margin Content

### Text in Margin

```markdown
::: {.column-margin}
This appears in the right margin.
:::
```

### Figures in Margin

````markdown
```{language}
#| column: margin
#| fig-cap: "Margin figure."

# code that produces a figure
```
````

Or for markdown images:

```markdown
::: {.column-margin}
![Margin image](small.png)
:::
```

### Tables in Margin

````markdown
```{language}
#| column: margin
#| tbl-cap: "Margin table."

# code that produces a table
```
````

### Mixed Content

`````markdown
Main text here.

::: {.column-margin}
Margin note explaining the main content.
:::

More main text.

`````

## Code Cell Layout Options

Control output placement from code cells:

### Column Option

````markdown
```{language}
#| column: page

# output spans page width
```
````

Options: `body`, `body-outset`, `page`, `page-inset`, `screen`, `screen-inset`, `margin`.

### Figure Column

Target figure outputs specifically:

````markdown
```{language}
#| fig-column: margin

# code that produces a figure
```
````

### Table Column

Target table outputs:

````markdown
```{language}
#| tbl-column: page

# code that produces a wide table
```
````

## Caption Location

### In Margin

````markdown
```{language}
#| fig-cap: "Figure with margin caption."
#| cap-location: margin

# code that produces a figure
```
````

### Document Default

```yaml
fig-cap-location: margin
tbl-cap-location: margin
```

## References in Margin

### Footnotes in Margin

```yaml
reference-location: margin
```

### Citations in Margin

```yaml
citation-location: margin
```

### Combined

```yaml
reference-location: margin
citation-location: margin
```

## Page Layout

### Document-Wide Settings

```yaml
format:
  html:
    page-layout: article   # Default
    page-layout: full      # Full width
    page-layout: custom    # Custom layout
```

### Grid Customization

```yaml
format:
  html:
    grid:
      sidebar-width: 300px
      body-width: 800px
      margin-width: 300px
      gutter-width: 1.5rem
```

## Two-Column Layout

Create side-by-side columns:

```markdown
::: {.columns}

::: {.column width="50%"}
Left column content.
:::

::: {.column width="50%"}
Right column content.
:::

:::
```

Adjust `width` percentages for unequal columns (e.g., `30%`/`70%`).

## Content Layout Divs

Arrange any content (images, tables, text) in grid layouts.

### Column Layout

```markdown
::: {layout-ncol=2}
![](image1.png)

![](image2.png)
:::
```

### Row Layout

```markdown
::: {layout-nrow=2}
Content 1.

Content 2.
:::
```

### Complex Layouts

Use layout array for precise control. Values represent relative widths:

```markdown
::: {layout="[[1,1], [1]]"}
First row, left.

First row, right.

Second row, full width.
:::
```

### With Spacing

Negative values add spacing between elements:

```markdown
::: {layout="[[40,-20,40], [100]]"}
Content 1.

Content 2.

Full width below.
:::
```

### Vertical Alignment

```markdown
::: {layout-ncol=2 layout-valign="bottom"}
Tall content.

Short content.
:::
```

Options: `top`, `center`, `bottom`.

### Layout Attributes

| Attribute       | Description         | Example                |
| --------------- | ------------------- | ---------------------- |
| `layout-ncol`   | Number of columns   | `layout-ncol=3`        |
| `layout-nrow`   | Number of rows      | `layout-nrow=2`        |
| `layout`        | Custom layout array | `layout="[[1,2],[1]]"` |
| `layout-valign` | Vertical alignment  | `layout-valign=center` |

## Tabsets

Create tabbed content:

```markdown
::: {.panel-tabset}

## Tab 1

Content for tab 1.

## Tab 2

Content for tab 2.

:::
```

### With Groups

````markdown
::: {.panel-tabset group="language"}

## R

```r
x <- 1
```

## Python

```python
x = 1
```

:::
````

Tabs with same group stay synchronized.

## Asides

For inline margin notes:

```markdown
Main text content.
[This is an aside that appears in the margin.]{.aside}
More main text.
```

## PDF Layout

PDF uses different layout system. Key options:

```yaml
format:
  pdf:
    documentclass: article
    geometry:
      - margin=1in
    classoption:
      - twocolumn
```

### Margin Notes in PDF

```yaml
format:
  pdf:
    documentclass: scrartcl # KOMA-Script
```

KOMA classes support margin content automatically.

## Resources

- [Quarto Article Layout](https://quarto.org/docs/authoring/article-layout.html)
- [Page Layout](https://quarto.org/docs/output-formats/page-layout.html)
- [Figures Layout](https://quarto.org/docs/authoring/figures.html#figure-panels)

# Markdown Linting

Quarto documents should follow standard [markdownlint](https://github.com/markdownlint/markdownlint) rules. This file covers only Quarto-specific allowances and configuration — refer to the markdownlint docs for general rules.

## Quarto-Specific Allowances

### Line Length (MD013)

Typically disabled for Quarto — prose paragraphs may be long and YAML/code lines can exceed limits.

### Duplicate Headings (MD024)

Repeated headers are common in structured Quarto documents (e.g., repeated "Example" sections).

### Multiple H1 (MD025)

Quarto documents may have multiple H1 headers, especially in books and multi-part documents.

### Inline HTML (MD033)

Quarto uses HTML in specific contexts:

- Shortcodes: `{{< shortcode >}}`
- Raw HTML blocks: ` ```{=html} `
- Elements like `<div>`, `<span>`, `<iframe>` for advanced layouts

### First Line H1 (MD041)

Quarto uses YAML front matter before the first heading, so MD041 should be disabled.

## Configuration

### Example `.markdownlint.yaml`

```yaml
default: true

MD013: false
MD024: false
MD025: false
MD033:
  allowed_elements:
    - div
    - span
    - iframe
MD041: false
```

### Example `.markdownlint-cli2.yaml`

```yaml
config:
  default: true
  MD013: false
  MD024: false
  MD025: false
  MD041: false

globs:
  - "**/*.md"
  - "**/*.qmd"
```

## Quarto Div Formatting

When using fenced divs, ensure proper blank-line spacing:

```markdown
Some text.

::: {.callout-note}
Note content here.
:::

More text.
```

Key points:

- Blank line before opening `:::`.
- Blank line after closing `:::`.
- Use `:::` (three colons) for both opening and closing divs, including when nesting.

## Resources

- [markdownlint Rules](https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md)
- [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)
- [Quarto Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html)

# Shortcodes

Shortcodes are special commands that expand into content at render time. Quarto provides several built-in shortcodes.

## Syntax

Shortcodes use double curly braces with angle brackets:

````markdown
{{< shortcode-name argument >}}
````

Or with named parameters:

````markdown
{{< shortcode-name param="value" >}}
````

## Video

Embed videos from various sources:

### YouTube

````markdown
{{< video https://www.youtube.com/embed/VIDEO_ID >}}
````

Or with just the ID:

````markdown
{{< video https://youtu.be/VIDEO_ID >}}
````

### Vimeo

````markdown
{{< video https://vimeo.com/VIDEO_ID >}}
````

### Local Video

````markdown
{{< video video.mp4 >}}
````

### Video Options

````markdown
{{< video https://youtu.be/VIDEO_ID
title="Video Title"
start="30"
aspect-ratio="16x9"
width="100%"

> }}
````

Options:

- `title` - Video title
- `start` - Start time in seconds
- `width` / `height` - Dimensions
- `aspect-ratio` - `16x9`, `4x3`, `1x1`, `21x9`

## Include

Include content from other files:

### Basic Include

````markdown
{{< include _content.qmd >}}
````

### Include Section

Include only part of a file:

````markdown
{{< include _content.qmd#section-id >}}
````

### Include with Path

````markdown
{{< include path/to/file.qmd >}}
````

### Usage Notes

- Included files are processed as Quarto markdown
- Use `_` prefix for files to exclude from rendering
- Paths are relative to the including document

## Embed

Embed output from Jupyter notebooks:

### Embed Cell Output

````markdown
{{< embed notebook.ipynb#cell-id >}}
````

### Embed with Options

````markdown
{{< embed notebook.ipynb#fig-plot echo=true >}}
````

Options:

- `echo` - Show source code (`true`/`false`)

### Finding Cell IDs

Cell IDs are set in notebook metadata or automatically generated.

## Meta

Access document metadata:

````markdown
The title is: {{< meta title >}}
Author: {{< meta author >}}
````

### Nested Metadata

````markdown
{{< meta format.html.theme >}}
````

### In Code Blocks

Works in code blocks too:

````markdown
```yaml
title: { { < meta title > } }
```
````

## Var

Access variables from `_variables.yml`:

### Define Variables

Create `_variables.yml`:

```yaml
version: 2.0.0
company: Acme Corp
```

### Use Variables

````markdown
Current version: {{< var version >}}
Published by {{< var company >}}.
````

### Nested Variables

```yaml
contact:
  email: info@example.com
  phone: 555-1234
```

````markdown
Email: {{< var contact.email >}}
````

## Env

Access environment variables:

````markdown
Home directory: {{< env HOME >}}
User: {{< env USER >}}
````

### Default Value

````markdown
{{< env MY_VAR default="not set" >}}
````

## Pagebreak

Insert a page break:

````markdown
Content before.

{{< pagebreak >}}

Content after (on new page in PDF).
````

Works across formats (PDF, Word, HTML print).

## Kbd

Describe keyboard shortcuts:

````markdown
Press {{< kbd Ctrl+C >}} to copy.
Save with {{< kbd Cmd+S >}} on Mac.
````

### Multiple Keys

````markdown
{{< kbd Ctrl+Shift+P >}}
{{< kbd Cmd-Option-Esc >}}
````

## Lipsum

Generate placeholder text:

````markdown
{{< lipsum 1 >}}
````

Generates one paragraph of Lorem Ipsum.

### Multiple Paragraphs

````markdown
{{< lipsum 3 >}}
````

## Placeholder

Generate placeholder images:

````markdown
{{< placeholder 400 300 >}}
````

Creates a 400x300 placeholder image.

### With Format

````markdown
{{< placeholder 400 300 format=svg >}}
````

## Version

Show Quarto version:

````markdown
Built with Quarto {{< version >}}.
````

## Contents

Rearrange document content:

````markdown
{{< contents heading >}}
````

Shows content under a specific heading. Useful for reorganizing included content.

## Conditional Shortcodes

Shortcodes can be format-specific:

````markdown
::: {.content-visible when-format="html"}
{{< video video.mp4 >}}
:::

::: {.content-visible when-format="pdf"}
See video at: https://example.com/video
:::
````

## Custom Shortcodes

Create custom shortcodes via extensions. Example extension structure:

```txt
_extensions/
└── my-shortcode/
    ├── _extension.yml
    └── my-shortcode.lua
```

## Shortcodes in Code

Shortcodes work in inline code and code blocks:

````markdown
`{{< meta title >}}`
````

```yaml
version: {{< var version >}}
```

## Escaping Shortcodes

To show shortcode syntax without executing:

````markdown
{{{< shortcode >}}}`
````

Or use raw block:

````markdown
```{.markdown shortcodes=false}
{{< shortcode >}}
```
````

## Examples

### Documentation Site

````markdown
# {{< meta title >}} v{{< var version >}}

{{< include _installation.qmd >}}

## Video Tutorial

{{< video https://youtu.be/TUTORIAL_ID >}}

## Keyboard Shortcuts

- Copy: {{< kbd Ctrl+C >}}
- Paste: {{< kbd Ctrl+V >}}

{{< pagebreak >}}

## Appendix

{{< include _appendix.qmd >}}
````

### Project Variables

`_variables.yml`:

```yaml
product:
  name: "MyApp"
  version: "2.1.0"
  year: 2024
```

Document:

````markdown
# {{< var product.name >}}

Version {{< var product.version >}} - Copyright {{< var product.year >}}
````

## Resources

- [Quarto Shortcodes](https://quarto.org/docs/extensions/shortcodes.html)
- [Video Embedding](https://quarto.org/docs/authoring/videos.html)
- [Includes](https://quarto.org/docs/authoring/includes.html)

# Tables

Quarto supports multiple table formats including pipe tables, list tables, and computational tables with extensive styling options.

## Pipe Tables

The most common table format:

```markdown
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |
```

### Column Alignment

Use colons to specify alignment:

```markdown
| Left    | Center  |   Right |
| :------ | :-----: | ------: |
| Left    | Center  |   Right |
| aligned | aligned | aligned |
```

- `:---` Left align
- `:---:` Center align
- `---:` Right align

### With Caption

```markdown
::: {#tbl-example}

| Column 1 | Column 2 |
| -------- | -------- |
| Data     | Data     |

Table caption.
:::
```

Reference with `@tbl-example`.

## Column Widths

### Using Dashes

More dashes = wider column:

```markdown
| Narrow | Wide Column |
| ------ | ----------- |
| A      | B           |
```

This creates approximately 33%/67% split.

### Explicit Widths

```markdown
| Column 1 | Column 2 |
| -------- | -------- |
| Data     | Data     |

: Caption {tbl-colwidths="[25,75]"}
```

### Document Level

```yaml
tbl-colwidths: [40, 60]
```

Or auto-fit:

```yaml
tbl-colwidths: auto
```

## List Tables

For complex content including multiple paragraphs, lists, and code blocks. Quarto natively supports pandoc list table syntax.

### Basic Syntax

Use bullet lists where top-level items (`-`) are columns and nested items are rows:

```markdown
::: {.list-table}

- - Header 1
  - Row 1, Col 1
  - Row 2, Col 1
- - Header 2
  - Row 1, Col 2
  - Row 2, Col 2

:::
```

### List Table Caption

Add a paragraph at the start for the caption:

```markdown
::: {.list-table #tbl-example}

Table caption here.

- - Column A
  - Column B
  - Column C
- - Data 1
  - Data 2
  - Data 3

:::
```

### List Table Attributes

| Attribute     | Description                 | Example          |
| ------------- | --------------------------- | ---------------- |
| `header-rows` | Rows in header (default: 1) | `header-rows=2`  |
| `header-cols` | Columns as headers          | `header-cols=1`  |
| `aligns`      | Column alignment            | `aligns="l,c,r"` |
| `widths`      | Relative column widths      | `widths="30,70"` |

### Header Configuration

```markdown
::: {.list-table header-rows=1 header-cols=1}

- -
  - Col Header 1
  - Col Header 2
- - Row Header
  - Data 1
  - Data 2

:::
```

Set `header-rows=0` for tables without headers.

### Row and Column Spans

Use empty spans with `colspan` or `rowspan`:

```markdown
::: {.list-table}

- - Column A
  - Column B
  - Column C
- - []{colspan=2}Spans two columns
  - Normal
- - Normal
  - Normal
  - Normal
- - []{rowspan=2}Spans two rows
  - Data 1
  - Data 2
- - Data 3
  - Data 4

:::
```

List tables also support row/cell attributes (`[]{.highlight}`, `[]{align=r}`), empty cells (lone `-`), and any markdown content in cells.

## Computational Tables

Tables generated from code:

````markdown
```{language}
#| label: tbl-summary
#| tbl-cap: "Summary statistics."

# code that produces a table
```
````

**Engine note — table rendering differs by engine:**

- **knitr engine**: Recognised table objects are rendered automatically (e.g. a data frame is printed as a markdown table without extra configuration).
- **jupyter engine**: Cells that return a display-protocol object auto-display as HTML in HTML output only. For portable output across all formats, print a markdown table string and set `output: asis`:

````markdown
```{language}
#| label: tbl-summary
#| tbl-cap: "Summary statistics."
#| output: asis

# print a markdown table string to stdout
```
````

See [engines.md](engines.md) for full engine details.

### Table Options

| Option             | Description      | Example      |
| ------------------ | ---------------- | ------------ |
| `tbl-cap`          | Table caption    | `"Summary."` |
| `tbl-subcap`       | Subcaptions      | `["A", "B"]` |
| `tbl-colwidths`    | Column widths    | `[40, 60]`   |
| `tbl-cap-location` | Caption position | `"top"`      |

## Caption Location

### Document Level

```yaml
tbl-cap-location: top
```

### Per Table

````markdown
```{language}
#| label: tbl-data
#| tbl-cap: "Data."
#| tbl-cap-location: bottom

# code that produces a table
```
````

Options: `top`, `bottom`, `margin`.

## Subtables

Multiple tables with shared caption:

```markdown
::: {#tbl-panel layout-ncol=2}

::: {#tbl-first}

| A   | B   |
| --- | --- |
| 1   | 2   |

First.
:::

::: {#tbl-second}

| C   | D   |
| --- | --- |
| 3   | 4   |

Second.
:::

Combined tables.
:::

See @tbl-panel, including @tbl-first.
```

### From Code

````markdown
```{language}
#| label: tbl-multi
#| tbl-cap: "Multiple tables."
#| tbl-subcap:
#|   - "Summary"
#|   - "Details"
#| layout-ncol: 2

# code that produces two tables
```
````

## Bootstrap Styling (HTML)

Add Bootstrap classes for styling:

```markdown
::: {#tbl-styled .striped .hover}

| A   | B   |
| --- | --- |
| 1   | 2   |

Styled table.
:::
```

Available classes:

| Class         | Effect                 |
| ------------- | ---------------------- |
| `.striped`    | Alternating row colors |
| `.hover`      | Highlight on hover     |
| `.bordered`   | Add borders            |
| `.borderless` | Remove borders         |
| `.sm`         | Smaller text           |
| `.responsive` | Horizontal scroll      |

Combine multiple classes: `::: {#tbl-name .striped .hover .bordered}`. Use `classes: plain` in code cells to disable default striping.

Quarto also processes HTML tables with `data-qmd` attribute for markdown content. Disable with `html-table-processing: none`.

## Table Layouts

Same as figures:

```markdown
::: {layout-ncol=2}

| A   | B   |
| --- | --- |
| 1   | 2   |

| C   | D   |
| --- | --- |
| 3   | 4   |

:::
```

## Long Tables

For tables spanning multiple pages (PDF), use a longtable option appropriate to your engine/package.

## Cross-Referencing

Tables are referenced with `tbl-` prefix:

```markdown
::: {#tbl-summary}

| Data |
| ---- |
| 1    |

Summary.
:::

See @tbl-summary for details.
```

## Resources

- [Quarto Tables](https://quarto.org/docs/authoring/tables.html)
- [Table Cross-References](https://quarto.org/docs/authoring/cross-references.html#tables)
- [Pandoc List Tables](https://github.com/pandoc-ext/list-table)

# YAML Front Matter

YAML front matter configures document metadata, format options, and execution settings.
It's located at the top of a document and is enclosed by `---`.

## Basic Document YAML

```yaml
title: "Document Title"
author: "Author Name"
date: today
format: html
```

## Title Block

### Basic Metadata

```yaml
title: "My Document"
subtitle: "A Subtitle"
author: "Jane Doe"
date: 2024-01-15
```

### Date Options

```yaml
date: 2024-01-15           # Specific date
date: today                 # Current date
date: now                   # Current date and time
date: last-modified         # File modification date
```

### Date Formatting

```yaml
date: today
date-format: "MMMM D, YYYY"  # January 15, 2024
date-format: "D/M/YYYY"      # 15/1/2024
date-format: iso             # 2024-01-15
date-format: long            # January 15, 2024
date-format: short           # 1/15/24
```

## Author Metadata

### Single Author

```yaml
author: "Jane Doe"
```

### Detailed Author

```yaml
author:
  name: "Jane Doe"
  email: jane@example.com
  url: https://janedoe.com
  orcid: 0000-0000-0000-0000
```

### Multiple Authors

```yaml
author:
  - name: "Jane Doe"
    email: jane@example.com
    affiliations:
      - name: "University A"
        department: "Statistics"
  - name: "John Smith"
    affiliations:
      - name: "University B"
```

### Affiliations

```yaml
author:
  - name: "Jane Doe"
    affiliations:
      - id: univ-a
        name: "University A"
        city: "Boston"
        state: "MA"
        country: "USA"
```

## Abstract and Keywords

```yaml
title: "Research Paper"
abstract: |
  This is the abstract.
  It can span multiple lines.
keywords:
  - data science
  - statistics
  - machine learning
```

## Format Configuration

### Single Format

```yaml
format: html
```

### Format with Options

```yaml
format:
  html:
    toc: true
    code-fold: true
    theme: cosmo
```

### Multiple Formats

```yaml
format:
  html:
    toc: true
  pdf:
    documentclass: article
  docx: default
```

## HTML Format Options

```yaml
format:
  html:
    toc: true
    toc-depth: 3
    toc-location: left
    toc-title: "Contents"
    number-sections: true
    code-fold: true
    code-tools: true
    code-line-numbers: true
    theme: cosmo
    css: custom.css
    fontsize: 1.1em
    linestretch: 1.5
    mainfont: "Georgia"
```

### Themes

```yaml
format:
  html:
    theme: cosmo          # Bootstrap theme
    theme:                # Custom theme
      light: cosmo
      dark: darkly
    theme: custom.scss    # Custom SCSS
```

Built-in themes: `default`, `cerulean`, `cosmo`, `cyborg`, `darkly`, `flatly`, `journal`, `litera`, `lumen`, `lux`, `materia`, `minty`, `morph`, `pulse`, `quartz`, `sandstone`, `simplex`, `sketchy`, `slate`, `solar`, `spacelab`, `superhero`, `united`, `vapor`, `yeti`, `zephyr`.

## PDF Format Options

```yaml
format:
  pdf:
    documentclass: article
    papersize: a4
    fontsize: 11pt
    geometry:
      - margin=1in
    toc: true
    number-sections: true
    colorlinks: true
    mainfont: "Times New Roman"
    monofont: "Fira Code"
```

### LaTeX Options

```yaml
format:
  pdf:
    include-in-header:
      - text: |
          \usepackage{custom}
    include-before-body:
      - file: before.tex
    keep-tex: true
```

## Word (DOCX) Options

```yaml
format:
  docx:
    toc: true
    number-sections: true
    reference-doc: template.docx
    highlight-style: github
```

## RevealJS Options

```yaml
format:
  revealjs:
    theme: dark
    transition: slide
    slide-number: true
    chalkboard: true
    controls: true
    progress: true
```

## Execution Options

```yaml
execute:
  echo: true # Show code
  eval: true # Run code
  warning: false # Hide warnings
  message: false # Hide messages
  error: false # Stop on error
  cache: true # Cache results
  freeze: auto # Freeze outputs
```

### Per-Format Execution

```yaml
format:
  html:
    execute:
      echo: true
  pdf:
    execute:
      echo: false
```

## Bibliography

```yaml
bibliography: references.bib
csl: apa.csl
link-citations: true
citation-location: margin
```

## Cross-References

```yaml
crossref:
  fig-title: "Figure"
  tbl-title: "Table"
  eq-prefix: "Equation"
  chapters: true
```

## Language and Localization

```yaml
lang: en-US
```

```yaml
lang: de
crossref:
  fig-title: "Abbildung"
  tbl-title: "Tabelle"
```

## Table of Contents

```yaml
toc: true
toc-depth: 3
toc-title: "Table of Contents"
toc-location: left # HTML only
```

## Numbering

```yaml
number-sections: true
number-depth: 3
number-offset: [0, 0] # Start from specific number
```

## Code Highlighting

```yaml
highlight-style: github
highlight-style: monokai
highlight-style:
  light: github
  dark: monokai
```

## Project Configuration

In `_quarto.yml`:

```yaml
project:
  type: website
  output-dir: _site

website:
  title: "My Site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
  sidebar:
    style: floating
    contents: auto

format:
  html:
    theme: cosmo
    toc: true
```

### Project Types

```yaml
project:
  type: website    # Website
  type: book       # Book
  type: default    # Default (single files)
  type: manuscript # Academic manuscript
```

## Book Configuration

```yaml
project:
  type: book

book:
  title: "My Book"
  author: "Jane Doe"
  date: today
  chapters:
    - index.qmd
    - intro.qmd
    - part: "Part I"
      chapters:
        - chapter1.qmd
        - chapter2.qmd
    - summary.qmd
  appendices:
    - appendix.qmd
```

## Parameters

```yaml
params:
  data_file: "data.csv"
  threshold: 0.5
  show_advanced: true
```

Use in document:

````markdown
```{language}
#| label: read-data

# access params$data_file (knitr) or params["data_file"] (jupyter) etc.
```
````

## Include Files

```yaml
include-in-header:
  - text: |
      <script src="custom.js"></script>
  - file: header.html

include-before-body:
  - file: before.html

include-after-body:
  - file: footer.html
```

## Metadata Files

```yaml
metadata-files:
  - _metadata.yml
```

Shared settings in `_metadata.yml`:

```yaml
author: "Jane Doe"
format:
  html:
    theme: cosmo
```

## Compute Engine

Use the `engine` and `jupyter` keys to select and configure the compute engine.
See [engines.md](engines.md) for options, auto-detection rules, and engine-specific behaviour.

## Resources

- [Quarto Document Options](https://quarto.org/docs/reference/formats/html.html)
- [PDF Options](https://quarto.org/docs/reference/formats/pdf.html)
- [Project Configuration](https://quarto.org/docs/projects/quarto-projects.html)