4.2 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}, [term]{.gls}, ::: {.glossary}; resolves across chapters |
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) |
fenced-divs.lua |
repairs ::: divs indented deeper than pandoc accepts (in numbered parts) |
Options (in _quarto.yml)
notecolor: "#B45309" # accent colour of notes, exercises, hints
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
glossary-page: glossary.html
glossary-back: "→ definition in context" # follows `lang` (en/fr/de) by default
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.
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.