4  Callouts and code blocks

Callouts allow important information to be highlighted. Code blocks allow code to be displayed or executed. This chapter presents both with examples drawn from a doctoral context.

4.1 The five callout types

Quarto defines five callout types, each with a precise semantic:

::: {.callout-specification}
## Title (optional) of the callout
Content of the callout, with `specification` taking one of the values
`note`, `tip`, `warning`, `important`, or `caution`, each associated with
a colour code and an icon in the callout header.
:::

4.1.1 callout-note — neutral information

::: {.callout-note}
## Jury composition

A Cnam thesis jury comprises at minimum a chair, two reviewers
(with hdr) and one or two examiners. The defence lasts approximately
45 minutes of presentation, followed by questions from the jury.
:::

Output:

NoteJury composition

A Cnam thesis jury comprises at minimum a chair, two reviewers (with hdr) and one or two examiners. The defence lasts approximately 45 minutes of presentation, followed by questions from the jury.

4.1.2 callout-tip — actionable advice

::: {.callout-tip}
## Start writing early

Start writing your thesis from the second year of doctoral study. Late writing is
the primary cause of exceeding the contractual thesis duration. Even imperfect drafts
are better than empty sections.
:::

Output:

AstuceStart writing early

Start writing your thesis from the second year of doctoral study. Late writing is the primary cause of exceeding the contractual thesis duration. Even imperfect drafts are better than empty sections.

4.1.3 callout-warning — pitfall to avoid

::: {.callout-warning}
## Do not rename chapters without updating the profile

If you rename a `.qmd` file, update the `chapters:` list in
`_quarto-en.yml` (or `_quarto-fr.yml`). Quarto does not automatically detect
missing files and will fail silently.
:::

Output:

AvertissementDo not rename chapters without updating the profile

If you rename a .qmd file, update the chapters: list in _quarto-en.yml (or _quarto-fr.yml). Quarto does not automatically detect missing files and will fail silently.

4.1.4 callout-important — non-negotiable point

::: {.callout-important}
## PDF/A-1b mandatory for theses.fr

The abes requires a PDF/A for archiving on theses.fr. This template
automatically generates a PDF/A-1b via `\usepackage[a-1b]{pdfx}`. Do not remove
this package from the template.
:::

Output:

ImportantPDF/A-1b mandatory for theses.fr

The abes requires a PDF/A for archiving on theses.fr. This template automatically generates a PDF/A-1b via \usepackage[a-1b]{pdfx}. Do not remove this package from the template.

4.1.5 callout-caution — danger with consequences

::: {.callout-caution}
## Do not use `date:` for the defence date

Quarto interprets the `date:` key as a JavaScript date and produces
"Invalid Date" for French date strings (e.g. "12 June 2026"). Use exclusively
the custom key `date-soutenance:` provided in this template.
:::

Output:

Mise en gardeDo not use date: for the defence date

Quarto interprets the date: key as a JavaScript date and produces “Invalid Date” for French date strings (e.g. “12 June 2026”). Use exclusively the custom key date-soutenance: provided in this template.

4.2 Callouts with title and collapsing

The title is added with a ## Title line inside the callout (as in the examples above). To make a callout collapsed by default (click to open), use the collapse attribute:

::: {.callout-tip collapse="true"}
## Click to see the tip (collapsed by default)

This callout is collapsed when the HTML document opens. In PDF, it always appears
in full (collapsing is an HTML-only feature).
:::

Output:

AstuceClick to see the tip (collapsed by default)

This callout is collapsed when the HTML document opens. In PDF, it always appears in full (collapsing is an HTML-only feature).

4.3 Code blocks — display only

To display code without executing it, use either a block delimited by backticks without a language specifier in curly braces, or a chunk with eval: false:

```python
# This block is displayed but not executed
import numpy as np
x = np.linspace(0, 10, 100)
print(x.mean())
```

Output:

# This block is displayed but not executed
import numpy as np
x = np.linspace(0, 10, 100)
print(x.mean())

To display the code of an executable chunk without executing it (useful for installation or configuration examples):

```{python}
#| eval: false
#| echo: true
# Installing dependencies
pip install matplotlib numpy pandas
```

Output:

# Installing template dependencies
# pip install matplotlib numpy pandas

AstuceMost useful chunk options

Table 4.1: Frequently used Quarto chunk options.

Option	Values	Effect
echo	true/false	shows or hides the code
eval	true/false	executes or skips the code
output	true/false	shows or hides the output
warning	true/false	shows or hides warnings
fig-cap	text	caption for the produced figure
label	fig-... or tbl-...	identifier for cross-reference

4.4 Code blocks — with Python execution

In this document, all executable code examples — including the matplotlib figures of Section 2.2 — use #| echo: true to display both the source code and the result. In a finalised thesis, code is generally hidden by switching to #| echo: false: only the figure or table appears, without the code that produced it.

NoteLanguages natively supported by Quarto

Quarto supports three scientific computing languages without additional configuration: Python, R, and Julia. The chunk option syntax (#| echo:, #| fig-cap:, etc.) and the cross-reference mechanism (#| label:) are identical for all three languages. This document illustrates Python only.

Official documentation:

• Python: https://quarto.org/docs/computations/python.html
• R: https://quarto.org/docs/computations/r.html
• Julia: https://quarto.org/docs/computations/julia.html

A Python chunk with eval: true (the default) executes the code and displays the output. Here is an example with pandas:

```{python}
#| echo: true
#| label: tbl-pandas
#| tbl-cap: "Descriptive statistics of trigonometric functions."
import numpy as np, pandas as pd
from IPython.display import Markdown

x = np.linspace(0, 2 * np.pi, 1000)
df = pd.DataFrame({r'$\sin(x)$':           np.sin(x),
                   r'$\cos(x)$':           np.cos(x),
                   r'$\tan(x)$ (clipped)': np.clip(np.tan(x), -5, 5)})
Markdown(df.describe().round(3).to_markdown())
```

Output:

import numpy as np, pandas as pd
from IPython.display import Markdown

x = np.linspace(0, 2 * np.pi, 1000)
df = pd.DataFrame({r'$\sin(x)$':           np.sin(x),
                   r'$\cos(x)$':           np.cos(x),
                   r'$\tan(x)$ (tronqué)': np.clip(np.tan(x), -5, 5)})
Markdown(df.describe().round(3).to_markdown())

Table 4.2: Descriptive statistics of trigonometric functions.

	\sin(x)	\cos(x)	\tan(x) (tronqué)
count	1000	1000	1000
mean	0	0.001	-0
std	0.707	0.708	2.335
min	-1	-1	-5
25%	-0.706	-0.705	-0.997
50%	-0	0.002	-0
75%	0.706	0.708	0.997
max	1	1	5

Notefreeze: auto in _quarto.yml

With execute: freeze: auto, Quarto stores cell results in _freeze/ and only recomputes them if the chunk code has changed. This considerably speeds up successive renders for theses with many computations.

Mise en gardeRemember to version the _freeze/ folder

If you version your thesis on GitHub and want reviewers to be able to compile without Python installed, commit the _freeze/ folder. The cached results are stored there and will be used instead of re-executing the code.