Welcome, Instructors

Welcome! These pages are written for instructors — anyone who wants to add a lesson to the Interactive Primer. This little corner of the tree is a worked set of examples you can read, copy, and adapt.

Every lesson is a single, self-contained .html file under concepts/. There is no build step: you write a page, drop it in the folder, and it works. The look-and-feel, the page header, the progress controls, and the navigation map are all added for you.

One tree of knowledge

Concepts form a tree (technically a DAG): each concept names the concepts it has as prerequisites, and that's the only structure the Primer needs. From those links it works out a learning order, an implied level for every concept, and the little three-column map you can see at the top and bottom of this page.

This page hangs directly off the root of the tree, and the Authoring Quizzes page lists this page as its prerequisite — so the map shows the root on the left and Quizzes on the right. Hover any node in the map to trace the connections.

One special child hangs off this page: The Orphans — a maintenance corner where any not-yet-connected concept is auto-attached until it finds its place on the tree.

What you can put on a page

Inside your content you have a small palette of building blocks. Pick the ones that suit your idea — there is no fixed template, and leaning on the same recipe everywhere makes the Primer feel repetitive.

Cards — each chunk of content is a <primer-card>.
Mathematics — <primer-math> typesets LaTeX, inline like a^2 + b^2 = c^2 or as a centred block:

\int_0^1 x^2 \, dx = \tfrac{1}{3}

Asides & callouts — <primer-vignette> tucks a fun digression behind a click, and <primer-theorem> states a formal law in a labelled box. Demos below.
Runnable code — <primer-code> is a themed, highlighted code block; add run and the learner can edit it and execute it in the browser.
Animations — <primer-manim> plays a narrated diagram on a Play button (see the Pythagorean Theorem).
Graphs & diagrams — <primer-chart> plots a function on axes (with optional sliders), <primer-chart-3d> does the same in a rotatable 3-D box, and <primer-geometry> draws figures you can step through. Worked examples are below.
Interactive practice — <primer-geometry-problem> is a figure the learner works: a fresh angle-chase generated every Refresh.
Video — <primer-video> embeds a YouTube clip behind a click-to-play thumbnail.
Links between concepts — <primer-ref> links to another concept and declares a prerequisite edge in the tree.
Quizzes — <primer-quiz> builds a test from questions you author inline. That's the next page: Authoring Quizzes.

A self-attested confidence rating (the stars below) is added to every page automatically — learners use it to tell the Primer how they're doing.

Asides & callouts

Two elements let you step out of the main flow. A <primer-vignette> is a collapsible digression: an intriguing question on the closed card, and the pay-off inside. Use it for the interesting-but-inessential — the "why", a scrap of history, a surprising case. Click to open:

n! counts the ways to arrange n objects in a row. There is exactly one way to arrange an empty set — the empty arrangement — so 0! = 1. It also makes the pattern n! = n \times (n-1)! keep working right down to 1! = 1 \times 0!.

The same element is the right home for a "Watch out!" note about a classic mistake — give it title="Watch out!". For a genuine theorem, law or key result, reach instead for <primer-theorem>, whose eyebrow reads "Theorem — {name}":

In a right-angled triangle, the square on the hypotenuse equals the sum of the squares on the other two sides: a^2 + b^2 = c^2.

Code you can run

On a programming page, <primer-code> renders a themed, lightly highlighted block. Add the run attribute and it grows Code / Output tabs and a Run ▶ button — the snippet is transpiled from TypeScript and executed in a sandboxed engine in the browser, with console.log feeding the Output tab. The Code pane is editable, so learners can tweak it and re-run. Press Run:

const nums: number[] = [3, 1, 4, 1, 5, 9, 2, 6]; const total = nums.reduce((a, b) => a + b, 0); console.log("sum =", total); console.log("max =", Math.max(...nums)); console.log("sorted=", [...nums].sort((a, b) => a - b).join(", "));

Write every example in TypeScript (beginner snippets are just untyped TS, identical to JavaScript; introduce : number, interface and the rest as the concepts arrive). Escape <, > and & in the body.

Graphs & diagrams

Maths is visual, so two elements let you draw. <primer-chart> plots a function on axes — give it sliders and the curve redraws live as the learner drags them. Here is y = a\,x^2; drag a to stretch the parabola:

<primer-geometry> draws figures — points, lines, angles and polygons — and can reveal a construction one step at a time, so an idea unfolds at the learner's pace. Use the controls beneath the figure to step through:

Both are themed automatically (they re-colour with light / dark / fun) and need no build step — you register each one in a small inline <script type="module"> at the foot of the page, just like the block powering the two figures above. For richer examples see Properties of sin(x) (charts with sliders) and Parallel Lines (stepped diagrams) — or browse the whole tree as one graph.

A third dimension

When an idea lives in space, <primer-chart-3d> renders a drag-rotatable 3-D box — points, vectors and surfaces projected to SVG, so it themes like every other figure and needs no WebGL. Drag to spin it, or move the sliders to change the vector:

Sliders sit below the figure by convention, and share the same registerChartSliders group machinery as the 2-D charts.

Practice, not just watching

<primer-geometry-problem> gives the learner a figure to work. A forward-chaining theorem engine synthesises a fresh angle-chase — some angles given, the rest blank — and it's different on every Refresh. Fill in the boxes, then Check. (The pool of theorems it may use is gated by a page's prerequisites; this demo borrows the parallel-lines toolkit.)

Bring in a video

<primer-video> embeds a YouTube clip. It shows only a thumbnail and a play facade until clicked, so nothing loads from YouTube until the learner asks for it: