Conventions¶
House rules for writing a page here. Readers browsing lessons do not need this file; it is for whoever is about to add one.
The shape of a lesson¶
02_Making_It_Stay/
interleaving/
README.md the lesson
examples/
interleaving.py the program
interleaving.out its recorded output
anki/
interleaving.txt the page as flashcards
One idea per folder. The folder name is the idea, in lower_snake_case, and it becomes a permanent URL — so name it for what it teaches, not for where it currently sits in the reading order.
A lesson may also carry anki/<stem>.txt, the page as a deck of flashcards in Anki's plain-text import format: header lines (#separator:tab, #notetype:Basic, #deck:, #tags:) and then one card per line, front, back and a tag separated by tabs. One fact per card, no HTML, no double quotes, and the page links to it from a Flashcards section. A folder may hold more than one example when the second is a tool for the reader, such as a checker for the book's exercises; its recorded output is whatever it prints with no arguments. A chapter may add a combined deck, anki/<chapter>_all.txt, generated by python3 tools/combine_anki.py <chapter folder>; regenerate it whenever a lesson deck changes, and add the chapter's --check line to .github/workflows/examples.yml.
Two kinds of page¶
A lesson makes a claim a program can show, and the program's output is on the page. Every page in chapters 01 to 04 is one.
An evidence-graded page is for a claim no program can check without invented data: sleep, exercise, food, brain chemistry, mindset. It lives in 05_Body_and_Brain and has no examples/ folder. In place of a program, every claim on it carries one of four grades, and the page says where the grade comes from:
| Grade | Means |
|---|---|
| well established | many experiments on people, replicated, in more than one lab |
| good evidence | consistent studies on people, but fewer, smaller, or with a caveat the page names |
| weak | a few small studies, mixed results, or evidence mainly in animals |
| speculative | a mechanism story with no direct test on learners |
Such a page gives no doses, recommends no supplement or drug, and offers no medical advice. Where the reader might want any of those, it says to ask a doctor. The grades are the page's honesty: a reader should be able to see at a glance which advice rests on decades of classroom experiments and which on one study of rats.
The page¶
Open with the title, then two lines that let a reader decide in five seconds whether this is their page:
# Interleaving: a blocked practice sheet skips the step the exam tests
**Level:** 101 · for anyone who did every problem at the end of the chapter and still froze on the exam
**One line:** A sheet of problems all of one kind lets you skip choosing the method; an exam mixes the kinds, so choosing is most of what it tests.
**Level:** is 101 / 201 / 301 / reference, then ·, then who it is for. The one-line summary states the claim, not the topic — "a blocked sheet skips the step the exam tests" is a one-liner; "an introduction to interleaving" is a table-of-contents entry.
Do not hard-wrap paragraphs. Write each paragraph as one long line and let the editor soft-wrap; Markdown collapses single newlines anyway, so wrapped and unwrapped prose render identically and unwrapped diffs are readable.
A short explanation in Polish¶
Every new lesson ends with a section ## Po polsku, w skrócie, placed just before See also, and every new chapter README.md carries one before its closing notes. It is a few paragraphs that explain the idea in Polish, in the author's own words: what the claim is, where the trap is, what the program shows. It is an explanation, not a translation of the page, so it may leave things out and may say them differently; a reader who knows only Polish should come away with the idea, and a reader who knows both should not find the page repeated. The owner asked for this on every page.
Output is generated, never typed¶
Mark the spot and let the tool fill it:
tools/run_examples.py runs the program and pastes what it actually printed, with a provenance line above the fence. Inside the markers is generated; outside is yours. The stem is bare — no path — so example stems must be unique repo-wide, which the tool enforces.
There is a second kind, <!-- source:stem -->, which pastes the program itself. Use it when the code is the lesson and a hand-copied fence could silently drift from the file CI runs.
python3 tools/run_examples.py # verify + refill
python3 tools/run_examples.py --update # record current output as the answer key
python3 tools/run_examples.py --check # write nothing, fail on drift (CI)
python3 tools/run_examples.py --only X # touch example X and nothing else
Use --only when someone else is working in the tree: a full --update re-records every key and would adopt whatever their half-finished example happens to print.
The program¶
Stdlib only. No exceptions. A reader must be able to run any page with the python3 already on their machine, and CI has no install step to prove it.
Deterministic. No clocks, no randomness, no network, no filesystem. The output is an answer key, so it has to be the same on every machine forever. If an example genuinely needs randomness, seed it explicitly in the file.
Written to be read aloud. These programs are teaching instruments: numbered sections, aligned columns, and prose in the print statements. A reader should be able to understand the output without the page, and the page without the output — the two reinforce, neither substitutes.
A short snippet in the prose puts its output in a trailing comment, on the line that prints it, so the whole thing survives a copy-paste:
Links¶
Link a folder by naming its README.md — [label](some_folder/README.md), never [label](some_folder/). The bare form works on GitHub and on the built site and fails everywhere else, including any local Markdown viewer, because MkDocs leaves it unrewritten.
A repo path in backticks should be a link, not bare code text: put the backticks in the label and a real relative path in the href.
Mark external links with ↗ so a reader knows they are leaving. Links to the math library ↗ and the other sibling libraries are external too, since each is its own site.
Nav order¶
The owner's preference, and the rule: the sidebar lists the chapters by name, A to Z. People look a subject up by name, so "Believing You Can" comes before "Knowing What You Know" whatever their numbers. The hook does this by itself: every numbered chapter lands where the CHAPTERS marker sits in the top-level NAV_ORDER list, sorted by the name shown in the sidebar, so a new chapter needs no edit there. The numbers stay in the folder names as the suggested reading order, which Start Here spells out.
Inside a chapter, the lessons keep their reading order, not A to Z, because each chapter is one argument and every lesson answers a question the one before it raised. That order lives in NAV_ORDER in mkdocs_hooks.py, keyed by folder path. Never set order by renaming files to 01_, 02_ — a filename is a permanent URL, and inserting one lesson would move every page after it. Unlisted pages sort alphabetically at the bottom.
The topic map¶
TOPICS.md is the second way in: every lesson sorted by subject into a tree with branches, plus threads that follow one idea across chapters. A new page needs a place in the tree, as one line with a link and a short description, and a ↪ entry in any other branch it belongs to. If a new lesson links to a lesson in another chapter, check whether the link belongs in one of the threads. The build enforces the first part: mkdocs build --strict fails if any lesson is missing from the map.
Before you commit¶
Both are what CI runs. --strict fails on a broken internal link, which is the failure most likely to reach the published site unnoticed.