# notes — Quarto extension for course notes The same copy lives in every 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 | | `version.lua` | the `version:` of `_extension.yml`, given to every html dependency: the files land in `site_libs/quarto-contrib/-/`, so each bump is a new URL and no browser keeps an older script | ## 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) points: 3 # points one question is worth (default 3) penalty: 1 # points one wrong statement costs (default 1) 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 `` 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 `` 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 — the verdict line — only when *all* of its options are in the right state, which is the exam's multiple-true-false rule. **Points.** A question is worth `points` (default 3). Every statement whose box disagrees with its truth value costs `penalty` (default 1): an unticked true statement and a ticked false one both count as one miss. The result floors at zero, so three misses empty a 3-point question and a fourth cannot take the total negative. The quiz's headline is the sum over its questions, "4 of 6 points". Set the pair book-wide under `quiz:` in `_quarto.yml`, or per quiz and per question: ```markdown ::::{.quiz title="..." points="6" penalty="2"} ::: {.question points="3"} ``` A question's own attribute wins over the quiz's, which wins over the metadata. In the PDF the boxes are empty, to tick with a pen, the points a question is worth are printed next to its heading, 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/`.