Adding structure

A well-structured Quarto document helps readers follow your analysis and allows Quarto to automatically generate tables of contents, numbered sections, and cross-references. You can add structure using headings, numbered elements (sections, figures, and equations), and citations or cross-references.

External Resources

For more detail, see for example HTML basics

Headings and Subheadings

Headings in Quarto follow the standard Markdown syntax using one or more hash (#) symbols. A single # creates a top-level heading, ## creates a subheading, and so on.

# Main Title

## Section Title

### Subsection Title

Which would result in:

Main Title

Section Title

Subsection Title

Quarto automatically interprets these heading levels to build a document hierarchy. This structure is reflected in the output and (if enabled) in a table of contents (toc: true in the YAML front matter).

For example, adding the following to your YAML header will generate an automatic table of contents based on your headings:

---
title: "My Analysis Report"
toc: true
number-sections: true
---

When number-sections: true is set, all headings are automatically numbered (1, 1.1, 1.2, etc.), and cross-references can be created for each section.

Numbering Figures and Equations

Quarto automatically numbers figures, tables, and equations that have captions. This numbering enables you to refer to them consistently throughout your text.

To number a figure, simply add a caption using the fig-cap option:

#| label: fig-distribution
#| fig-cap: "Distribution of scores by group."
library(ggplot)

ggplot(data, aes(x = group, y = score, fill = group)) +
  geom_boxplot()

See below how this caption will appear in addition to the figure:

Figure 1: Distribution of scores by group.

To reference it in text, use the label you assigned: See @fig-distribution for an overview of the score distributions. would result in: See Figure 1 for an overview of the score distributions.

For equations, numbering occurs when you assign a label inside the LaTeX math block:

$$
E = mc^2 \quad
$$ {#eq-myequation}

\[ E = mc^2 \quad \tag{1}\]

You can then refer to this equation as @eq-myequation in your text, which will render as “(1)” or “Equation 1” depending on the format. Here it results in: Equation 1.

Numbering Sections

When you include number-sections: true in your YAML front matter, Quarto automatically numbers all top-level and nested headings. This is especially useful in reports, theses, or papers where hierarchical organization matters. The numbering adjusts dynamically as you add or rearrange content, ensuring consistent structure throughout the document.

Adding References and Citations

Quarto uses Pandoc’s citation system, allowing you to cite sources from a bibliography file. In your YAML header, include the path to a .bib file (in BibTeX format):

---
title: "My Report"
bibliography: references.bib
---

You can then cite works in-text using the @ symbol and the citation key from your .bib file: As shown in @smith2021, the results confirm the hypothesis.

To include a list of references (a bibliography) at the end of your document, simply add a # References heading — Quarto will automatically populate it during rendering.

Example of inline citations:

External Resources

For more detail, see Quarto citations

Back to top

References

Doe, Jane. 2022. Reproducible Analysis with Quarto. 1st ed. New York: Open Science Press.
Smith, John. 2021. “Data Visualization Techniques for Modern Research.” Journal of Data Science Education 15 (2): 101–20. https://doi.org/10.1234/jdse.2021.15.2.101.