A Title That Says Exactly What the Note Covers

Open with a short paragraph that frames the whole note in plain language: what it covers, why it matters, and how the pieces connect. Name the key terms in bold on first use. Prefer warm, precise prose over bullet dumps.

In one line. A one- or two-sentence spine of the whole note, set off as a blockquote so a reader skimming gets the gist before diving in.

Contents
  1. How a note is put together
  2. Headings, sections, and cross-references
  3. Captioned blocks: equations, figures, tables
  4. Diagrams with NeuralFlow
  5. Charts (math in KaTeX, words in SF Pro)
  6. Callouts, intuition, and proofs
  7. Code and pseudocode
  8. Voice and finishing

How a note is put together

Every note follows the same spine, which you can see above:

  1. a title (# …) that names the content, not the week or lecture;
  2. the numbering <style> block (copy it verbatim into every note);
  3. an intro paragraph and a > In one line. blockquote;
  4. a Contents list inside a note-card with anchor links; then
  5. the sections, separated by --- rules.

The body then works top-down: each section states its idea in prose, then shows the supporting equation, diagram, chart, or table as a captioned block. Aim for a reader who has never seen the topic: motivate before you formalise.

Headings, sections, and cross-references

Give every heading an explicit id so it can be linked and stays stable if you reword the title:

Then cross-reference by that number: "as shown in §3.1" or "(§1)". Because the numbers are generated from the heading order, they always match the Contents list — just keep your written §N.M references in step if you reorder sections.

A note on subsections

This subsection exists only so you can see the automatic 2.1 numbering in action. Use subsections when a section has two or more distinct moves; otherwise keep it flat.

Captioned blocks: equations, figures, tables

Anything worth pointing at — a display equation, a diagram, a table — goes in a :::caption block. It gets a numbered, captioned frame (Equation 3.1, Figure 4.1, …) and an anchor you can link to. The title="…" is the caption text; write math in it as $…$ (see §5 for the rule).

Equations

Frame a display equation like this — a short, self-contained statement of one fact:

$$ a^2 + b^2 = c^2 . \tag{3.1} $$
Equation 3.1: The Pythagorean theorem relates the sides of a right triangle

Refer back to it as (eq. eq-pythagoras). Use \underbrace{…}_{…} to annotate parts of an equation inline, and prove non-obvious steps in full rather than asserting them.

Tables

For tables, use type="table" raw="1" and hand-write the HTML inside a table-compact wrapper (this gives you full control over headers and alignment):

quantitysymbolvalue
legs$a,\ b$3, 4
hypotenuse$c$5
Table 3.1: A compact table. Put math in cells as $…$ and keep headers short.

Diagrams with NeuralFlow

Use a neuralflow block for any flow, pipeline, architecture, or computation graph. Nodes carry a [Title | detail] label (math via $…$); edges are A --> B : label. Status colours are used consistently: inputs status=info, data status=off, intermediates status=warn, output status=ok.

Figure 4.1: A forward flow: input $x$ is transformed into $y$ through one processing step. Left-to-right is the natural reading direction.

When you show a backward / gradient pass, mirror the forward diagram: flow the other way, colour the edges red ({#dc2626}), label each edge with the local slope, and put the accumulated quantity in each node.

Figure 4.2: The mirrored backward pass: each red edge is a local slope, and each node's value is the product of the edge labels on the path back from the output.

Charts (math in KaTeX, words in SF Pro)

Plots are Chart.js blocks: a <div id="chart-…"> placeholder plus a <script class="chartjs-config" data-target="…"> with the config as JSON.

Always set "katexLabels": true. The engine then renders the legend and axis titles as HTML around the canvas, so you can follow the one rule that governs every label and caption in these notes:

Math → KaTeX, words → SF Pro Display. Wrap every mathematical symbol in $…$; leave plain words unwrapped. So a legend entry reads move $x$ (slope 1), and an axis title reads value $f, g$ — the letters render as crisp KaTeX, the words in the page font.

One gotcha worth memorising, because the two contexts escape backslashes differently:

Figure 5.1: A minimal chart. The legend and both axis titles carry KaTeX: $f(x) = x$ and $g(x) = x^2$.

Callouts, intuition, and proofs

Two devices carry the "why," so the main line of prose stays clean:

A blockquote holds an aside — an intuition, a derivation, or where a formula comes from:

Where it comes from. State the principle in one or two sentences, then the key step. Keep it to the insight; the full algebra can go in an equation block.

A note-card groups a small, self-contained aside (a definition, a checklist, a worked micro-example) into a bordered card:

Definition — right triangle. A triangle with one $90^\circ$ angle. Its longest side, opposite the right angle, is the hypotenuse $c$; the other two are the legs $a$ and $b$. Everything in §3.1 follows from this.

When a result is not obvious, prove it — show the algebra with \underbrace annotations rather than asserting the answer.

Code and pseudocode

Use a fenced python block for real code, and a text block for pseudocode. Align trailing # comments so shapes and intent line up:

def hypotenuse(a, b):
    return (a**2 + b**2) ** 0.5      # √(a² + b²) — the Pythagorean theorem
Repeat until converged {
    step  = compute_update()          # one move
    state = state - step              # apply it
}

Voice and finishing

A few habits keep the notes consistent:

Ready to write? Copy this file, rename it for your topic, keep the <style> block and the front-matter shape, delete these example sections, and fill in your own. The rendered result and this source are your two references.