Writing notes

The standard every Margin note is written to, how a note is structured, and the workflow for adding or improving one.

The goal of every note: a student who reads it, works the examples and does the practice questions should be able to answer any exam question on that topic, and should never need a textbook, a revision guide or another website.

This page covers what a note contains and the workflow. The same standard lives in the repository as content/README.md, next to the notes, so it is in front of anyone (or any model) writing one. The Note format reference is the full reference for the Markdown.

Where notes live#

content/subjects.json             Subjects in display order, each listing its course slugs
content/courses/<course>.json     One course: title, short label, level, paper, units -> note ids
content/notes/<course>/<path>.md  One note per topic

A note's id is its path under content/notes without .md, for example physics-as/kinematics/equations-of-motion. Its URL is /notes/<id>.

The id must start with the note's course.
Every note must be listed in exactly one unit of its course manifest, in teaching order. The manifest controls the order in the sidebar and the Previous and Next links.

Frontmatter#

---
title: Equations of Motion
course: physics-as
level: AS            # AS or A2
paper: AS            # short label shown with the note: P1, M1, S2, AS, A2, Paper 4 ...
needs:               # note ids to understand first
  - physics-as/kinematics/displacement-velocity-acceleration
leads: []            # note ids this one unlocks
related: []          # same idea, neither before nor after
---

Field	Required	Meaning
`title`	Yes	The note's title. Quote it if it contains a colon.
`course`	Yes	The course slug, matching a file in `content/courses/`
`level`	Yes	`AS` or `A2`
`paper`	Yes	The short label shown with the note
`needs`	No	Prerequisites, shown as Builds on
`leads`	No	Topics this unlocks, shown as Leads to
`related`	No	Same idea from another angle, shown as See also

The frontmatter is validated against NoteDocument in src/lib/notes/document.ts, which is the contract for anything that writes notes, including generated ones.

Shape of a note#

Notes are long-form teaching, not bullet summaries. A typical topic note is 1,500 to 3,500 words. Use this order, adapting where the topic demands:

Opening paragraph, with no heading. What the topic is, why it matters and where it shows up in the exam. Two to four sentences in plain language.
Core ideas under ## headings, each built up from intuition to the formal statement. Explain why before what. Define every term the first time it appears.
Key results in :::key and definitions in :::definition. Use the syllabus's own wording for definitions that are examined word for word.
Methods in :::method, as numbered steps, for any procedure students must carry out.
Worked examples: at least four per note, graded from routine to exam-hard, in the style and difficulty of real Cambridge questions. Every example has a full solution showing the working an examiner wants, with the mark-earning steps visible.
Common mistakes in :::warning. Name the exact misconception and the fix.
Exam technique in :::exam: command words, how marks are awarded, what examiners repeatedly report students getting wrong, and how to set out the answer.
Practical skills in :::practical, in the sciences: apparatus, method, variables, uncertainties, sources of error, improvements, and how the practical paper asks about it.
Summary in :::summary near the end: the five to ten things to remember.
Practice questions in a :::question block, followed by :::solution{title="Answers"} with full worked answers, not just final numbers. Six to ten questions of mixed difficulty, the last two at the hardest exam standard.

Quality bar#

Correct. Every number in an example and answer is checked, ideally with a quick script. Every definition matches the current Cambridge syllabus wording. No made-up past-paper references: do not cite specific paper codes or years unless certain.
Complete. The course manifest covers every learning outcome in the current syllabus for that course, in syllabus order. Nothing in the syllabus is missing; nothing beyond it is presented as examinable. Extension material is marked as such in a :::tip.
Clear. Short paragraphs, one idea per paragraph, concrete before abstract. Bold the term being defined, not random phrases.
Exam-ready. Each note teaches how marks are earned, not just the content.
Consistent. The same notation throughout a subject, British spelling, SI units, sentence-case headings, no emoji and no exclamation marks.

Exam tip

The quickest test of a note: pick a real exam question on the topic and check that everything needed to answer it, including how to lay out the answer, is in the note.

Workflow#

Create or edit the Markdown file under content/notes/<course>/.
Add the note id to the right unit in content/courses/<course>.json, in teaching order.
Link it up: fill in needs, leads and related, and add it to the leads of the notes it builds on.
Run the checker for the course:
```
pnpm notes:check physics-as
```
Read the note in the app with pnpm dev and work every example yourself.
Open a pull request.

pnpm notes:check compiles notes exactly as the build does and fails on invalid frontmatter, broken needs, leads and related links, notes missing from the manifest, bad graph blocks and KaTeX errors. Zero problems is the bar. It prints a summary such as:

24 notes, 61,240 words, 13 live courses, 0 problems

Small fixes#

For a typo or a wrong number, you do not need a local setup. Open the note's file on GitHub, choose the edit button, and propose the change as a pull request. The docs work the same way: every page has an Edit this page on GitHub link at the bottom.