1  Document structure and formatting

This chapter presents the basic building blocks of any Quarto document: heading hierarchy, numbering, section cross-references, and inline formatting.

1.1 Heading hierarchy

Quarto supports four levels of numbered headings in this template (parameter number-depth: 4 in _extension.yml). The syntax uses Markdown hashes:

# Chapter heading (level 1)

## Section heading (level 2)

### Subsection heading (level 3)

#### Sub-subsection heading (level 4)

In PDF, these levels correspond respectively to the LaTeX commands \chapter, \section, \subsection, and \subsubsection. In HTML, they generate the tags <h2> through <h5> (with <h1> reserved for the book title).

1.1.1 Demonstration subsection

This is a ### in context. The automatic numbering produces “1.1.1” here.

1.1.1.1 Demonstration sub-subsection

And this is a ####, numbered “1.1.1.1”. Beyond this level, Quarto stops numbering — use lists or bold paragraphs if you need a fifth level.

AvertissementRecommended maximum depth

A four-level numbered outline is generally the maximum acceptable in a thesis. A deeper outline is often a sign that the structure needs rethinking.

1.2 Numbered and unnumbered sections

By default, all headings from level 1 to 4 are numbered. To remove the numbering, add the class {.unnumbered}:

## Section without number {.unnumbered}

For front matter and back matter pages (acknowledgements, abstract, conclusion…), combine {.unnumbered} with {.toc-black} — the latter class instructs the Lua filter to display the title in black in the table of contents, and triggers roman numeral page numbering in the front matter when pagestyle-sections: true:

# Conclusion {.unnumbered}

# Acknowledgements {.unnumbered .toc-black}
Important.unnumbered vs .unnumbered .toc-black
  • {.unnumbered} alone: unnumbered heading, displayed in colour in the toc (chapters in the thesis body: introduction, conclusion).
  • {.unnumbered .toc-black}: unnumbered heading, displayed in black in the toc (front matter and back matter sections).

Never put {.unnumbered} on a numbered body chapter (chapters 1, 2, 3…) — it would be inconsistent with the overall structure.

1.3 Section cross-references (@sec-)

To create a cross-reference to a section, you need to: (1) give an identifier to the target heading with {#sec-label}, then (2) reference it with @sec-label:

## Heading hierarchy {#sec-headings}

As explained in @sec-headings, levels range from `#` to `####`.

Output:

As explained in Section 1.1, levels range from # to ####.

Quarto automatically resolves the number and hyperlink in both formats.

AstuceLabel naming convention

Use the prefix sec- for sections, fig- for figures, tbl- for tables, eq- for equations. These prefixes are required by Quarto for cross-references to work correctly in both output formats.

1.4 Short title (short-title)

When a chapter or section title is too long to fit in the PDF running header or in the table of contents, use the short-title attribute:

# A really very long title that overflows into the header {short-title="Short title"}

## A subsection with an extremely long title {short-title="Short title"}

The short title is used in the running header (recto/verso page header) and in the table of contents. The long title remains unchanged in the body of the text.

Astuce

Aim for 40 to 50 characters maximum for a short-title. Beyond that, it may also overflow depending on the layout.

1.5 Inline formatting

1.5.1 Emphasis and code

**bold**, *italic*, ***bold italic***, `inline code`
~~strikethrough~~, ^superscript^, ~subscript~
:::

Output:

bold, italic, bold italic, inline code, strikethrough, superscript, subscript.

ImportantAcademic use of bold and italic

In a thesis, bold and italic serve to mark terminology at first introduction, or to cite a book title. Using them to decorate text or emphasise entire sentences is a practice to avoid.

1.5.2 Underline

Markdown has no native syntax for underlining. Quarto uses the span notation with the .underline class:

[underlined text]{.underline}

Output:

underlined text.

In PDF, Pandoc generates \underline{…}; in HTML, a <span> with text-decoration: underline. The <u>text</u> syntax works in HTML but is ignored in PDF.

Mise en gardeUnderlining should be avoided in a thesis

Underlining is a legacy of the typewriter era, when italic was not available. In a typeset document, it is reserved for hyperlinks. To highlight a term, use *italic* or **bold**.

1.5.3 Lists

- First unordered item
- Second item
  - Sub-item (2-space indentation)

1. First ordered item
1. Second item
   a. Sub-item (3-space indentation)

Output:

  • First unordered item
  • Second item
    • Sub-item (2-space indentation)
  1. First ordered item
  2. Second item
    1. Sub-item (3-space indentation)
NoteThe written number does not matter

Pandoc only reads the number of the first item (to determine the counter start); all subsequent numbers are ignored and auto-incremented. These two syntaxes produce the same output:

1. First
2. Second
3. Third
1. First
1. Second
1. Third

The 1. 1. 1. convention is even recommended: no need to renumber if an item is inserted or moved. The same logic applies to sub-lists: a. a. a. is sufficient to obtain a., b., c.…

1.5.4 Task lists

The - [ ] / - [x] syntax produces a task list. The case of x does not matter (X works too):

- [ ] Write the introduction
- [x] Choose the Quarto template
- [ ] Submit to the thesis supervisor

Output:

NoteDifferent rendering depending on the output format

In HTML, Quarto generates real <input type="checkbox"> elements (disabled, non-interactive).

In PDF (pdflatex), Pandoc uses the mathematical symbols $\square$ (empty box) and $\boxtimes$ (checked box) from the amssymb package. The appearance is correct but typographically different from HTML checkboxes.

Mise en gardeUse in a thesis

Task lists are suited to working notes, methodological appendices, or a README. In the thesis body, prefer a plain unordered list accompanied by a state verb (“completed”, “in progress”…): it is more neutral and more consistent with academic register.

1.5.5 Blockquotes

> "Typography is the craft of endowing human language with a durable visual form."
>
> — Robert Bringhurst [@Bringhurst2004]

Output:

“Typography is the craft of endowing human language with a durable visual form.”

— Robert Bringhurst (Bringhurst 2004)

Mise en gardeDefinition lists in pdflatex

Pandoc’s definition list syntax (term\n: definition) is supported by Quarto but produces no particular visual style in pdflatex. If you need formatted definition lists, use a Markdown table (see Section 3.4) or a raw LaTeX environment.

1.5.6 Footnotes

Quarto offers two syntaxes for footnotes.

Inline syntax — the note is written directly in the text, between ^[ and ]:

The Cnam was founded in 1794^[Decree of the National Convention of 19 Vendémiaire
Year III (10 October 1794).] on the initiative of Abbé Grégoire.

Output:

The Cnam was founded in 17941 on the initiative of Abbé Grégoire.

Reference syntax — the footnote call and its content are separated. Useful for long notes or to keep the main text readable:

The thesis must be deposited on theses.fr[^deposit] before the defence.

[^deposit]: National thesis portal managed by the abes,
    accessible at <https://theses.fr>.

Output:

The thesis must be deposited on theses.fr2 before the defence.

In PDF, both syntaxes produce a numbered footnote at the bottom of the page. In HTML, they produce an interactive footnote (clickable number with a back-reference to the call site).

AstuceWhich syntax to choose?

Prefer the inline syntax ^[…] for short notes (one sentence) — the content remains visible while writing. Use the reference syntax [^label] for long or multi-paragraph notes, and to avoid visually cluttering the Markdown source when the note exceeds two lines.

1.5.7 Page breaks

Quarto provides the shortcode to insert a page break compatible with both output formats:

End of this section's content.

{{< pagebreak >}}

Start of the next section.

In PDF, generates \newpage. In HTML, it inserts a page-break-after: always style rule — with no visible effect on screen, but useful if the HTML page is printed from the browser.

Astuce\newpage vs \clearpage

If you need \clearpage (flushes pending floats before jumping) rather than \newpage, use a raw LaTeX block inside a {.content-visible when-format="pdf"}:

::: {.content-visible when-format="pdf"}
```{=latex}
\clearpage
```
:::

In a thesis with many figures, \clearpage is often preferable to prevent floats from accumulating and appearing well after their insertion point in the text.

Mise en gardeManual page breaks should be used sparingly

As a general rule, let LaTeX manage the layout. Manual page breaks solve a local problem but can create others further on in the document (blank pages, displaced floats). Prefer to adjust them at the very end of writing, once the content is fixed.

Bringhurst, Robert. 2004. The Elements of Typographic Style. 3ᵉ éd. Hartley & Marks.

  1. Decree of the National Convention of 19 Vendémiaire Year III (10 October 1794).↩︎

  2. National thesis portal managed by the abes, accessible at https://theses.fr.↩︎