Night-mode styling, French cross-references, and the log through Part VI
- 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>
This commit is contained in:
1 parent
afb816f459
commit
f7fa60ba81
62 files changed
+3552
-852
No files matched your search
+147
-1
@@ -8,16 +8,21 @@ documents its syntax in the comment at its top; this page is the overview.
|
||||
| `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}`, `[term]{.gls}`, `::: {.glossary}`; resolves across chapters |
|
||||
| `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)
|
||||
@@ -31,11 +36,111 @@ quiz:
|
||||
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
|
||||
@@ -100,6 +205,30 @@ printed at the end of the chapter with a page reference back to the quiz
|
||||
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
|
||||
@@ -123,3 +252,20 @@ _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/`.
|
||||
Reference in new issue
Block a user