Skip to content

View or edit on GitHub

This page is synchronized from doc/Quarto.md. Last modified on 2026-11-02 10:41 CET by dependabot[bot]. Please view or edit the original file there; changes should be reflected here after a midnight build (CET time), or manually triggering it with a GitHub action (link).

Quarto

Setup

Quarto runs .qmd Python chunks through a Jupyter kernel named python3. If none is registered, quarto render/quarto preview fails with:

jupyter_client.kernelspec.NoSuchKernel: No such kernel named python3

Register one for the poetry virtual environment (one-time, per-machine — not tracked by the repository, so redo this if you recreate your virtual environment):

poetry run python3 -m ipykernel install --user --name python3 --display-name "Python 3 (trase)"

Defaults

_quarto.yml at the root of the repository sets the defaults for every .qmd file in the repository:

  • format: gfm — render to GitHub-flavoured Markdown, so documents are readable on GitHub alongside the code that produced them
  • execute: echo: false — show the results, not the code that produced them

It deliberately does not name a Jupyter kernel. Quarto picks the engine from the chunk language — knitr for ```{r}, Jupyter for ```{python} — and the Jupyter engine defaults to the kernel named python3. Naming a kernel in a document (jupyter: trase-py3.11) only ties the repository to one person's local kernel names, so don't.

A document overrides a default by setting the same key in its own header. Note that a format: key replaces the default rather than adding to it, so a document that wants a PDF as well as the Markdown has to name both:

format:
  gfm: default
  pdf: default

Boilerplate

Because the defaults above are shared, a document usually only needs a title. Here is a Python document:

---
title: "My analysis"
---

Here is a plot:

```{python}
import plotly.io as pio
import plotly.express as px

pio.renderers.default = "png"

fig = px.bar(x=["a", "b", "c"], y=[1, 3, 2])
fig.show()
```

And the same for R:

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "5/22/2021"
---

## Air Quality

@fig-airquality further explores the impact of temperature on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Save the file as my_analysis.qmd. Here are some useful commands:

# live preview
quarto preview my_analysis.qmd

# render to a markdown file
quarto render my_analysis.qmd

Render one document at a time. _quarto.yml makes the whole repository a Quarto project, so a bare quarto render tries to render every .qmd in it.