Files
ProcessControl/_extensions/notes/README.md
T

13 KiB

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
history.lua ::: {.history} quiet grey boxes for historical context beside the text
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/<name>-<version>/, so each bump is a new URL and no browser keeps an older script

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)
  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)
field: math                 # study field, for the badge colour on the index (math, phys, cs, bi, …)

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:

  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

::::{.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.

Exercises and quizzes are numbered chapter.n; in an appendix the chapter is its letter, A.1, A.2, … (and handin.sh A.1 hands one in).

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 — 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:

::::{.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:

::: {.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.

Historical context

History beside the text — who found a result, an old paradox, how a notion came about — is not material to study, so it does not go in the purple "to go further" box (which is for optional mathematics):

::: {.history title="Achilles and the tortoise"}
Zeno of Elea …
:::

It renders as a quiet grey box with an italic heading, "History" (following lang: Geschichte, Histoire; override with history: label: "…"), in the muted token, so night mode and high contrast follow by themselves. In a multilingual book, wrap the body in language divs and write the title as title="@tr{key}", as for .further.

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/.