- theme.scss and figures draw with the extension's --calc-… tokens; light/dark pair plus the high-contrast button; a11y highlight style for html - figure labels split so none leaves its viewBox in any language - _quarto-fr.yml: French cross-reference prefixes - notes extension synced to 2.8.18 - conv/: Parts IV, V and VI logged, pasted terminal output redacted Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
notes — Quarto extension for course notes
The same copy lives in every course (<course>/_extensions/notes/). Each filter
documents its syntax in the comment at its top; this page is the overview.
| File | What it does |
|---|---|
calc-notes.lua |
\begin{calc} / calc* derivations with \note{} / \mnote{}; label with $$ … $$ {#eq-x} |
exo.lua |
::::{.exo} exercises with .hint and .solution placed where written; hand-in mode |
quiz.lua |
::::{.quiz} tick-box self-checks with a Check button and per-option .why |
glossary.lua |
.gls-def, \gls{key}, \gls[variant]{key} in maths (shows the variant, links to the entry), [term]{.gls}, ::: {.glossary}; resolves across chapters, and links also work inside a definition and in a figure caption (pdf too) |
latex-tables.lua |
tabular environments rendered as HTML tables |
i18n.lua |
one source, several languages: ::: {.de}, […]{.fr}, @tr{key} |
si-mathjax.lua |
\SI, \si, \num, \ang in HTML (PDF uses siunitx) |
further.lua |
::: {.further} purple "to go further" notes, for material beside the lecture |
fenced-divs.lua |
repairs ::: divs indented deeper than pandoc accepts (in numbered parts) |
theme.css |
the palette every part shares, in light and in night mode |
high-contrast.css |
the high-contrast pair, after GitHub's two high-contrast VS Code themes |
narrow.css |
keeps the page inside a phone screen: formulas, code and tables scroll in place |
Options (in _quarto.yml)
notecolor: "#B45309" # accent colour of notes, exercises, hints
notecolor-dark: "#e0a361" # its night value; by default the same hue, lifted
exo:
pdf-solutions: inline # PDF: solutions in place (default: end of chapter)
label: "Exercice" # labels follow `lang` (en/fr/de); override any of
hint: "Indice" # label, hint, solution, solutions, part, page
quiz:
pdf-answers: inline # PDF: answers under the quiz (default: end of chapter)
label: "Quiz" # labels follow `lang` (en/fr/de); override any of
question: "Question" # label, question, answers, answer, check, reset,
check: "Vérifier" # right, wrong, score, true, false, hint, page
siunitx-html: mathjax # leave \SI & co. to a MathJax siunitx extension
furthercolor: "#6B3FA0" # the accent of the "to go further" notes
furthercolor-dark: "#c09ae8"
glossary-page: glossary.html
glossary-back: "→ definition in context" # follows `lang` (en/fr/de) by default
high-contrast: true # stronger palette, both modes (default: off)
Night mode
The extension carries one palette, in theme.css, and every colour it draws
with is a token on it. A book gets night mode by offering the two themes:
format:
html:
theme:
light: [cosmo]
dark: [darkly]
Quarto then shows its light/dark toggle and sets body.quarto-dark, which is
what the dark values key off — never prefers-color-scheme, so a book
configured light-only stays light for a reader whose system is dark.
A book's own notecolor and furthercolor are kept in night mode, not
replaced: the print value is too dim on a dark ground, so it is lifted to a
light tone at the same hue (oklch(from … 0.78 c h)). A book that wants a
particular night colour sets notecolor-dark: / furthercolor-dark:. The
book's colour itself stays available as --calc-notecolor-src.
The tokens, should a book's own css want them: --calc-ink, --calc-muted,
--calc-line, --calc-grid, --calc-accent-a/-b/-c, --calc-danger,
--calc-surface, --calc-faint, --calc-shadow, --calc-domface,
--calc-domtop, and the two from the metadata, --calc-notecolor and
--calc-furthercolor.
A pinned highlight-style needs no pair: Quarto ships the light and the dark
variant of its bundled themes (github, github-dark, …) and swaps them with
the toggle as soon as a book offers two themes. theme.css deliberately leaves
code colours alone.
Generated line art (main img[src$=".svg"]) is inverted in night mode, hue
rotated so blue stays blue. An svg that is a photograph, or that brings its
own dark palette, opts out with class="no-invert".
A built svg figure writes each colour as a token with its light value as the
fallback, var(--calc-ink, #1a1a1a): inlined in the page it follows the
three modes, while an <img> and rsvg-convert (the PDF) draw the fallback.
No prefers-color-scheme block in figure CSS: it follows the system, not the
page's toggle.
Plots from code (matplotlib). A line plot (curves, points, bars, a few
colours) is an svg: fig-format: svg under format: html only, a
transparent figure and axes background, black ink and accents that survive
invert + hue-rotate(180°); it then turns with the page like other line art. A
plot whose colours carry data (a colour map, a surface, an image) is a png on
an opaque white ground and is never inverted — inverting would reverse the
scale; in night mode it shows as a white card, like a photograph. A png is
never inverted, so it needs no no-invert.
Text drawn in an accent colour needs 4.5:1, a stroke only 3:1: for text, mix
in a fifth of ink, color-mix(in srgb, var(--calc-accent-a) 80%, var(--calc-ink)) — same hue, and it passes in all four modes.
High contrast
high-contrast.css is a second pair of themes, taken from GitHub's
GitHub Light High Contrast and GitHub Dark High Contrast VS Code
themes (the Primer light_high_contrast / dark_high_contrast scales). It
rides on top of the ordinary pair — the light/dark toggle keeps working — and
restyles the page, not only the extension: canvas, headings, links, the
sidebar and the table of contents, code blocks and their syntax colours,
tables, block quotes and the notes environments.
Following the two themes, it separates by outline rather than by fill: muted
ink goes to full strength, borders take border.default, and the tinted
panels of .exo, .further, .quiz and the glossary lose their tint for a
full-strength accent edge.
The reader switches it with the half-circle button next to Quarto's
light/dark toggle in the navigation bar. The choice is kept in localStorage
(notes-contrast) and applied from the <head> on the next page, so nothing
flashes. High contrast and night mode are two separate axes: either toggle
works whatever the other one says.
Three ways in, in order of precedence:
- what the reader last picked with the button;
high-contrast: truein_quarto.yml, for the whole book;- the reader's system setting,
prefers-contrast: more, which is watched, so changing it takes effect without a reload — until the reader picks for themselves, after which their choice stands.
Measured on a chapter of Analysis, contrast against the page (WCAG AA is 4.5); captions re-measured with 2.8.4, which gives them the muted token:
| body | link | toc | caption | code keyword | comment | |
|---|---|---|---|---|---|---|
| ordinary light | 11.5 | 5.4 | 5.4 | 6.4 | — | — |
| high contrast light | 18.9 | 8.0 | 8.0 | 18.9 | 8.1 | 5.0 |
| ordinary dark | 15.9 | 6.5 | 6.5 | 6.3 | — | — |
| high contrast dark | 17.6 | 9.2 | 9.2 | 17.6 | 9.7 | 11.7 |
Exercises
::::{.exo title="Stefan-Boltzmann law"}
Statement.
1. First part.
:::{.hint}
A hint for this part.
:::
:::{.solution}
Solution of part 1.
:::
2. Second part.
:::{.solution}
Solution of part 2.
:::
::::
Each solution is labelled with its part ("Solution (Part 2)"). Override with
:::{.solution part="b"}. Empty solutions (placeholders) are not shown.
Quizzes
::::{.quiz title="Landau notation"}
::: {.question}
Decide which statements are true.
- [x] $n + 2 = o(n^2)$
- [ ] $n = \mathcal{O}(\log^2 n)$
:::{.why}
$n$ eventually outgrows every power of $\log n$.
:::
:::
::::
- [x] is a true statement, - [ ] a false one. A .why inside an option
explains that option; a .why written directly in the question explains the
question as a whole. Both are shown only to a reader who got it wrong.
A quiz holds any number of ::: {.question} divs (a quiz with none is read as
a single question). Numbering is chapter.n, as for exercises.
In HTML the options are real checkboxes and one Check button at the end of the quiz marks every option, reveals the explanations for the mistakes and scores the quiz; Reset clears it. A question counts as correct only when all of its options are in the right state — the exam's multiple-true-false rule.
In the PDF the boxes are empty, to tick with a pen, and the answers are
printed at the end of the chapter with a page reference back to the quiz
(quiz: pdf-answers: inline keeps them in place).
Correct answers are part of the built HTML, as solutions are: the quiz is a self-check, not an assessment.
To go further
Material that sits beside the course's own statement — a formal construction, a proof the lecture skipped, a pointer to the wider theory:
::: {.further}
Everything in here is optional.
:::
::: {.further title="Cantor pairing"}
…
:::
In a multilingual book, wrap the body in ::: {.de} / {.fr} / {.en} divs as
usual, and write the title as title="@tr{key}" — a literal title= is an
attribute and stays in whatever language you typed it.
It renders as a purple box, headed "To go further" (following lang: Vertiefung,
Pour aller plus loin). Override the heading with further: label: "…" and the
colour with furthercolor: in _quarto.yml. Use it whenever the handwritten
pages carry a "to go further" annotation.
Tools
Hand in solutions. Renders only the chosen exercises to _handin/, and
lists each one with any empty solution:
_extensions/notes/handin.sh 1.3 1.5 --subtitle "Series 2"
_extensions/notes/handin.sh 2 --no-statement # all of chapter 2, solutions only
_extensions/notes/handin.sh 1.2 --profile fr # a language of a multilingual book
_extensions/notes/handin.sh --help
Keep every course on the same version. After changing the extension in one course, push it to all the others:
_extensions/notes/sync.sh --dry-run # what would change
_extensions/notes/sync.sh
A copy that was edited in place (or has a higher version:) is skipped with a
diff, so nothing is overwritten silently. Bump version: in _extension.yml
when you change something.
Check contrast and phone width. Loads every page of a build in light,
dark and both high-contrast modes, at 320 and 1280 px, and measures every
visible text node (folds opened, opacity counted) against its ground, and
anything wider than the screen. Point it at _book/ or at a scratch render;
it works on a temporary copy and never writes to the build:
quarto render --profile fr --to html --output-dir /tmp/fr-test
_extensions/notes/audit.py /tmp/fr-test # 320 and 1280 px
_extensions/notes/audit.py _book --widths 320 --json out.json
It prints the worst ratio per mode, every text under 4.5:1 with its element
and colour, and every page wider than the screen; the exit status is 1 if
anything fails. audit-page.js is the part that runs in the page. Needs
Playwright's chrome-headless-shell under ~/.cache/ms-playwright/.