Writing in Quarto

Markdown, Citations, and Cross-References

Daniela Palleschi

March 25, 2026

Overview

  • Markdown basics: text formatting and structure
  • Headers and document organisation
  • Citations and APA formatting
  • Cross-referencing sections and example sentences
  • Inline R for dynamic reporting

Source vs. visual editor

I recommend using the Source editor (e.g., in YAML editor: source), as it helps you understand the underlying syntax

Source editor

editor: source
  • Write raw Markdown
  • Syntax always visible
  • Easier to debug
  • Builds better habits

Visual editor

editor: visual
  • Formatting applied visually
  • Point-and-click tables
  • Built-in Zotero integration
  • Can silently reformat Markdown

Markdown basics

Text formatting and structure

Text formatting

Markdown Output
**bold** bold
*italic* italic
***bold italic*** bold italic
`code` code
~~strikethrough~~ strikethrough
H~2~O H2O
R^2^ R2

Headers

# Chapter title (H1)
## Section (H2)
### Subsection (H3)
#### Subsubsection (H4)

Tip

In a Quarto book, H1 (#) is reserved for the chapter title in the YAML. Use H2 (##) for your first-level sections within a chapter.

Lists

- unordered item
- another item
  - nested item

1. ordered item
2. another item
   1. nested item
  • unordered item
  • another item
    • nested item
  1. ordered item
  2. another item
    1. nested item

Block elements

> This is a blockquote.
> Useful for quoting stimuli or definitions.
>
> -- Attributed author

This is a blockquote. Useful for quoting stimuli or definitions.

– Attributed author

Callout boxes

> This is a blockquote.
> Useful for quoting stimuli.
::: callout-tip
A tip callout.
:::
::: callout-note
A note callout.
:::
::: callout-warning
A warning callout.
:::
::: callout-important
An important callout.
:::

This is a blockquote. Useful for quoting stimuli.

Tip

A tip callout.

Note

A note callout.

Warning

A warning callout.

Important

An important callout.

Citations

BibTeX, Zotero, and APA formatting

Setting up a bibliography

In your YAML:

bibliography: references.bib
csl: apa.csl

references.bib: BibTeX file with your references
apa.csl: Citation Style Language file for APA formatting

Tip

Download apa.csl from the Zotero CSL repository or run:

download.file(
  "https://www.zotero.org/styles/apa",
  here::here("apa.csl")
)

Citation syntax

Syntax Output
@Bates2015 Bates et al. (2015)
[@Bates2015] (Bates et al., 2015)
[-@Bates2015] (2015)
[@Bates2015, p. 12] (Bates et al., 2015, p. 12)
[@Bates2015; @Gelman2020] (Bates et al., 2015; Gelman, 2020) 
Mixed-effects models were fitted following @Bates2015. All analyses were conducted in R [@R2024].

Mixed-effects models were fitted following Bates et al. (2015). All analyses were conducted in R (R Core Team, 2024).

Getting BibTeX entries

  • Zotero: export library or single item as BibTeX (recommended)
  • Google Scholar: Cite → BibTeX → copy into references.bib
  • DOI: use doi2bib.org to generate BibTeX from a DOI
  • R packages: citation("lme4") gives a citable reference
citation("lme4")
toBibtex(citation("lme4"))

APA formatting tips

  • Use csl: apa.csl: Quarto handles the rest automatically
  • Author-date in text: @Bates2015 → Bates et al. (2015)
  • References section: add references.qmd with ::: {#refs} :::
  • Running head, double spacing, line spacing: set in YAML or reference .docx

Note

For APA 7th edition PDF output, use documentclass: apa7 in your YAML and the apa7 LaTeX class.

Cross-references

Figures, tables, sections, and equations

Cross-reference prefixes

Type Label prefix Reference
Figure fig- @fig-mass
Table tbl- @tbl-demo
Section sec- @sec-results
Equation eq- @eq-model
Example exm- @exm-stimulus

Figures

```{r}
#| label: fig-mass
#| fig-cap: "Body mass by condition."
ggplot(...)
```

In prose:

As shown in @fig-mass, body mass differed by condition.

→ “As shown in Figure 1, body mass differed by condition.”

Tables

```{r}
#| label: tbl-desc
#| tbl-cap: "Descriptive statistics by condition."
tbl3 |> gt()
```
Descriptive statistics are presented in @tbl-desc.

→ “Descriptive statistics are presented in Table 1.”

Sections

## Results {#sec-results}

## Discussion {#sec-discussion}

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

→ “As discussed in in Section 4…”

Equations

$$
y_i = \beta_0 + \beta_1 \text{Tense}_i + \beta_2 \text{Lifetime}_i + \varepsilon_i
$$ {#eq-model}

The model is specified in @eq-model.

\[ y_i = \beta_0 + \beta_1 \text{Tense}_i + \beta_2 \text{Lifetime}_i + \varepsilon_i \tag{1}\]

The model is specified in Equation 1.

Numbered examples

  • for linguistic example sentences
  • Pandoc’s (@) syntax auto-numbers examples continuously across the document:
(@ex-good) The manager hired the assistant.
(@ex-bad) *The assistant was hired the manager.

As shown in (@ex-good), the active form is grammatical.
  1. The manager hired the assistant.
  2. *The assistant was hired the manager.

As shown in (1), the active form is grammatical.

gb4e for PDF

  • for more control (e.g., sub-examples (1a, 1b), glosses, alignment) use the gb4e LaTeX package in PDF output

Add to your YAML:

format:
  pdf:
    include-in-header:
      text: |
        \usepackage{gb4e}
        \noautomath
  • gb4e is a LaTeX package and only works in PDF output!!

Then use raw LaTeX blocks in your .qmd:

\begin{exe}
  \ex \label{ex-good} The manager hired the assistant.
  \ex \label{ex-bad}  *The assistant was hired the manager.
\end{exe}
  1. The manager hired the assistant.
  2. *The assistant was hired the manager.

Cross-referencing gb4e

As shown in example (\ref{ex-good}), the active form is grammatical.

Warning

gb4e cross-references only resolve in PDF output. Use (@) syntax if you need cross-references in both HTML and PDF.

Inline reporting

Dynamic values in prose

Inline R code

Embed R values directly in prose:

The sample comprised `r n_distinct(df$px)` participants (*M*~age~ = `r round(mean(df$age, na.rm = TRUE), 1)` years).

The sample comprised 48 participants (Mage = 23.4 years).

APA-style statistics

Statistic Markdown Output
Mean *M* = 310.8 M = 310.8
SD *SD* = 155.9 SD = 155.9
t-test *t*(48) = 2.31 t(48) = 2.31
p-value *p* < .001 p < .001
Cohen’s d *d* = 0.45 d = 0.45

Tip

In APA 7, statistical symbols (M, SD, t, p, F) are italicised. Use *...* in Quarto markdown.

✏️ Your turn

Open exercises/session1.qmd and follow the exercises for Session 1.

~15 minutes

Summary

  • Markdown handles most formatting needs
  • Cross-references use @label syntax with type prefixes
  • (@) for numbered linguistic examples
  • Inline R keeps statistics in sync with your analysis
Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting linear mixed-effects models using lme4. Journal of Statistical Software, 67(1), 1–48. https://doi.org/10.18637/jss.v067.i01
R Core Team. (2024). R: A language and environment for statistical computing. R Foundation for Statistical Computing. https://www.R-project.org/