- 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>
272 lines
11 KiB
Markdown
272 lines
11 KiB
Markdown
# 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`)
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
1. what the reader last picked with the button;
|
|
2. `high-contrast: true` in `_quarto.yml`, for the whole book;
|
|
3. 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
|
|
|
|
```markdown
|
|
::::{.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
|
|
|
|
```markdown
|
|
::::{.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:
|
|
|
|
```markdown
|
|
::: {.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:
|
|
|
|
```bash
|
|
_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:
|
|
|
|
```bash
|
|
_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:
|
|
|
|
```bash
|
|
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/`.
|