quarto-documents

name

quarto-documents

description

Create and edit single-file Quarto documents (.qmd) that output to HTML, PDF, or Word. Use when the user asks to "create a Quarto document", "write a report in Quarto", "make a research paper", "set up a manuscript", "create an article", "add figures to my Quarto file", "add citations", "set up cross-references", or needs help with YAML frontmatter, figure layouts, tables, math, code blocks, or bibliography configuration in a single .qmd file.

Quarto Single-File Documents

Create and edit standalone .qmd documents that render to HTML, PDF, and/or DOCX from a single source file. This covers articles, reports, manuscripts, and any document that lives in one file (as opposed to multi-file book or website projects).

Critical Rule: Relative Paths

All links to images, data files, stylesheets, bibliography files, and other resources MUST use paths relative to the .qmd file's location or relative to the project root. Never use absolute paths.

# CORRECT — relative to the .qmd file
![Figure](images/plot.png)
![Figure](../figures/result.png)
bibliography: references.bib

# WRONG — absolute paths break portability
![Figure](/absolute/path/to/project/images/plot.png)

Document Setup

Minimal YAML Frontmatter

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

Multi-Format Output

---
title: "My Report"
format:
  html:
    toc: true
    number-sections: true
  pdf:
    documentclass: article
    geometry: margin=1in
  docx:
    reference-doc: template.docx
---

Academic Article Frontmatter

---
title: "Article Title"
author:
  - name: "First Author"
    orcid: "0000-0000-0000-0000"
    email: "[e-mail]"
    corresponding: true
    affiliations:
      - name: "University Name"
        department: "Department"
abstract: |
  Abstract text here. Can span multiple lines.
keywords: [keyword1, keyword2, keyword3]
date: today
bibliography: references.bib
csl: nature.csl
format:
  html:
    toc: true
    embed-resources: true
  pdf:
    documentclass: article
    keep-tex: true
---

Manuscript Project Type

For scholarly articles with supporting notebooks, use type: manuscript:

# _quarto.yml
project:
  type: manuscript

manuscript:
  article: index.qmd
  notebooks:
    - notebook: notebooks/analysis.qmd
      title: "Data Analysis"
  meca-bundle: true

format:
  html: default
  jats: default
  pdf: default

Figures

Basic Figure with Cross-Reference

![Descriptive caption](images/figure.png){#fig-results width=80%}

As shown in @fig-results, the data indicates...

Multi-Panel Figures

::: {#fig-comparison layout-ncol=2}
![Method A](images/method-a.png){#fig-method-a}

![Method B](images/method-b.png){#fig-method-b}

Comparison of two methods. (a) Method A results. (b) Method B results.
:::

Custom Layout Proportions

The layout attribute accepts a 2D array where numbers represent proportional widths. Negative values insert spacing.

::: {#fig-complex layout="[[60,40], [100]]"}
![Main result](images/main.png){#fig-main}

![Detail](images/detail.png){#fig-detail}

![Wide panel](images/wide.png){#fig-wide}

Complex figure. (a) Main result. (b) Detail view. (c) Full-width panel.
:::

Computational Figures (Python)

```{python}
#| label: fig-distribution
#| fig-cap: "Data distribution"
#| fig-width: 8
#| fig-height: 5
#| echo: false

import matplotlib.pyplot as plt
import numpy as np

data = np.random.normal(0, 1, 1000)
plt.hist(data, bins=30)
plt.xlabel('Value')
plt.ylabel('Frequency')
plt.show()
```

Computational Figures (R)

```{r}
#| label: fig-scatter
#| fig-cap: "Scatter plot of variables"
#| warning: false

library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) + geom_point() + theme_minimal()
```

Tables

Markdown Table with Cross-Reference

| Variable | Mean | SD   |
|:---------|-----:|-----:|
| Age      | 45.2 | 12.3 |
| Score    | 85.5 |  8.7 |

: Descriptive statistics {#tbl-stats}

See @tbl-stats for details.

Computational Tables

```{python}
#| label: tbl-results
#| tbl-cap: "Regression coefficients"

import pandas as pd
from IPython.display import Markdown
from tabulate import tabulate

df = pd.DataFrame({
    'Variable': ['Intercept', 'X1', 'X2'],
    'Estimate': [2.34, 0.56, -0.23],
    'p-value': [0.001, 0.003, 0.045]
})
Markdown(tabulate(df, headers='keys', tablefmt='pipe', showindex=False))
```

Citations and Bibliography

Setup

bibliography: references.bib
csl: apa.csl  # Download from github.com/citation-style-language/styles
link-citations: true

Citation Syntax

@smith2020 showed that...           # Smith (2020) showed that...
[@smith2020]                        # (Smith, 2020)
[@smith2020; @jones2021]           # (Smith, 2020; Jones, 2021)
[@smith2020, p. 42]                # (Smith, 2020, p. 42)
[-@smith2020]                       # (2020) — suppress author

References Section

Place at end of document:

## References

::: {#refs}
:::

Cross-References

All cross-referenceable elements need the correct label prefix:

Element	Label prefix	Reference syntax	Renders as
Figure	#fig-	@fig-label	Figure 1
Table	#tbl-	@tbl-label	Table 1
Equation	#eq-	@eq-label	Equation 1
Section	#sec-	@sec-label	Section 1
Listing	#lst-	@lst-label	Listing 1
Theorem	#thm-	@thm-label	Theorem 1

Equations

Inline: $E = mc^2$

Display with label:
$$
\hat{\beta} = (X'X)^{-1}X'y
$$ {#eq-ols}

Reference: @eq-ols shows the OLS estimator.

Aligned equations:
$$
\begin{aligned}
y_i &= \beta_0 + \beta_1 x_{1i} + \epsilon_i \\
\epsilon_i &\sim N(0, \sigma^2)
\end{aligned}
$$ {#eq-model}

Code Blocks

Execution Options

```{python}
#| echo: false       # Hide code, show output
#| eval: true        # Execute the code
#| warning: false    # Suppress warnings
#| output: asis      # Raw output (for markdown tables)
#| code-fold: true   # Collapsible code (HTML only)
#| cache: true       # Cache results
```

Global Execution Options

execute:
  echo: false
  warning: false
  freeze: auto    # Reuse cached output when source unchanged
  cache: true

Callout Blocks

::: {.callout-note}
## Key Point
Important information here.
:::

::: {.callout-warning}
Proceed with caution.
:::

::: {.callout-tip collapse="true"}
## Click to expand
Hidden details.
:::

Five types: note, warning, important, tip, caution.

Conditional Content

Show content only in specific formats:

::: {.content-visible when-format="html"}
Interactive HTML-only content here.
:::

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

Resources

Consult these reference files for detailed configuration:

• references/pdf-configuration.md — PDF-specific YAML options, LaTeX classes, fonts, margins, preamble customization
• references/html-configuration.md — HTML themes, TOC options, code display, self-contained output, comments
• references/authoring-syntax.md — Complete syntax reference for figures, tables, citations, equations, callouts, divs, spans, footnotes, and embedding