Two keys move you through the whole lecture, forward and back, and holding Shift jumps a whole column.

• Forward is Space, ↓, →, Enter or PageDown. It uncovers the next piece of the chunk, then moves on to the next chunk.
• Back is ↑, ←, PageUp or Backspace. It puts the last piece away, and leaves the chunk only once that chunk is back where it started.
• Shift-→ and Shift-← move a whole column, from any slide and not only the first of one. Shift-← goes to the top of the column you are in first, so returning to the start of a part and leaving it are the same key. Press forward now:

You just uncovered a segment: in the source, a line containing nothing but --- cuts a chunk into segments, as long as it is outside a block of code. The first segment is on screen when you arrive; forward uncovers the next, back puts it away.

A faint ⌄ at the foot of the slide says the next forward press will leave the column. It is the one thing about where you are that the slide cannot show you by itself. There is nothing to click.

The cockpit – the speaker view, which is discussed later on – shows you what comes next. With it open, look at this slide there: the segment the next forward press will reveal is already drawn in place, hatched and inside a dashed frame, so you can read ahead without the audience seeing it. Only the immediately next one; the segments behind it stay hidden.

Segments let you pace a dense slide during a talk instead of putting all of it up at once, and this third one is here so you can see them chain. In print.html and print-notes.html they run together as one flowing body, so nothing is lost on paper.

Some chunks have extra detail behind a chevron button: click one, or press 1…9 for the n-th. This chunk has two of them – try both.

print.html and print-notes.html print every expansion as an indented aside where it stood in the source, so the reading copy loses nothing.

Click any figure, block of code or formula inside the chunk you are on. It opens in a card in the middle of the screen, with the slide dimmed behind it.

# Click this block to zoom it. Useful when a line
# matters more than the slide.
def anonymity_set(observations, senders):
    return {s for s in senders if plausible(s, observations)}

Inside an opened card: drag to pan, wheel or + - to zoom, 0 to reset, Esc or a click to close. With a speaker window open, the projection follows which card you opened, how far you zoomed and where you panned, so what you are inspecting is what the audience sees.

In the projection, dragging pans instead of selecting, and holding Alt – option on a Mac – turns selection back on. Hold the key and the slide becomes selectable and the cursor changes; let go and dragging pans again. The selection survives the key release so you can reach Cmd-C, and Esc clears it.

Links behave two ways, and which one you want depends on the window you are in. A plain click follows the link in a new tab of that window. Clicked in the speaker view, that is you checking a source while the projection stays where it was. Clicked in the projection, the page opens in front of the audience.

The small QR-code symbol after the link is the second way: it puts the address on both screens, large, with a scannable code beside it, so people can open the link on their own phones. Click the address to open it anyway; Esc or the next slide clears it. Shift-clicking the link itself does the same.

Try it on this one: the group behind the tool. The symbol is what you want while an audience is watching.

The codes are drawn when the lecture is built, one per external address in the source. style: {link-codes: off} leaves them out.

Press O now – the letter O, not the digit zero, which resets the zoom instead. The view zooms out to show every chunk at once, laid out in its columns, with an outline round the one you were on.

• Drag to pan the board, wheel to zoom it.
• Click a slide to go there – one click both picks it and leaves the board.
• Arrow keys move the outline without landing, and the board follows, because the slide you want is often off screen.
• O again or Enter lands on the outlined slide; Esc leaves without moving.

The board shows the shape of the lecture, which is usually enough to find the part you want. With a speaker window open, both windows enter, pan, zoom and leave together.

T shows a list of every named column. Click an entry to jump there; T again closes the panel.

A column with no {#id} does not appear – the unnamed opening column that holds the title slide stays out of the list. The {#id} is also what a cross-reference points at: a [text](#some-id) link anywhere in the body finds it.

Press / from anywhere – you do not have to be in overview first. A panel opens and every slide whose heading or body contains what you type is listed with the sentence it matched, the term highlighted.

↑ ↓ pick a result, Enter or a click goes there, Esc closes without moving. If you opened the search from the overview board, the board follows your pick as you move down the list, so a match on the far side of the lecture comes into view while you are still choosing.

Search is what you want when you remember a topic but not which slide it is on. It reads the whole chunk, so a word that appears only in a sentence the projection never shows still finds its slide.

Unless you say otherwise, the slide is the first sentence of every paragraph plus any **bold** phrases from the rest. This chunk is written that way – press C twice and watch what appears and disappears.

It asks two things of you. Every paragraph has to open with a sentence that stands on its own, because that sentence is the slide. After it, a bold phrase becomes a bullet of its own, so it has to read as one. Everything unbolded is for print.html and print-notes.html.

The two bullets above are that rule applied: neither is a list in the source – each is a **bold** phrase inside a sentence the projection is holding back.

Bold selects, it does not stress. A bullet is set like the sentence above it, and one word inside a bold phrase is stressed with *em*, like this one. On paper the phrase is bold and the stressed word bold in the accent colour; style: {bold: …} and style: {print-bold: …} change either look for a whole lecture, and the chunk on the style: block lists the six.

That suits a chunk that argues, where every paragraph has a point to open with. It is the wrong fit when the chunk wants continuous explanation instead, and the next chunk shows the alternative.

You are reading the projector version of this chunk: the bullets above sit inside a ::: slide block and this paragraph does not. Press C and this paragraph appears; press C again and it goes away.

Use ::: slide when the slide wants tight bullets while the argument wants prose. A chunk with neither block behaves exactly as Option 1 does, and the next chunk shows the other half of Option 2.

Press C twice on this chunk and watch one paragraph come and go while nothing else on the slide moves. That paragraph sits inside a ::: script block, which is the reverse of the last chunk: everything outside the block is the screen, and the block alone is what you say.

Use it when the screen half is the big half: the three made-up findings below are already the whole slide, and pressing C does not touch them. Wrapping them in a ::: slide block would mean marking nearly the whole chunk in order to exclude one paragraph, so marking that paragraph is the shorter way to say the same thing.

• One request in seven is answered differently once the crawler is instrumented.
• The gap is widest on the sites that serve the most third-party script.
• It closes again if the crawler waits between requests.

A ::: slide block wins wherever a chunk has one; failing that, a ::: script block puts everything outside itself on the screen; failing both, Option 1 applies. Three rules, checked in that order, on each chunk separately, so one lecture normally uses all three.

The notes pane sizes itself: up to three lines of text, one line once you have emptied it, and folded away entirely on a chunk that has no notes. Once you drag it, the height stays where you put it and is remembered across lectures and reloads. The slide above gives up exactly the space the notes take, so the copy of the projection keeps the projector's proportions instead of stretching.

Put the thumbnails down the right-hand side if the screen has width to spare: they get larger and their text becomes readable, so you can read ahead in the strip instead of only reading your position off it. The strip's height and its width are remembered separately.

An annotation is public, speaker notes are private.

A talk with a written-out script and minimal slides needs the script where you can glance at it. K in the speaker view rearranges the window: your notes for this chunk as cards down a rail, the projection small in the corner, the clock in the header. Space says the next card; when the cards of this beat are said, it clicks the projector, and the clicks stand in the same column as diamonds, so you read one list from top to bottom. Backspace takes one press back, whatever it was. Enter skips to the next slide.

A paragraph in a > note: is a card, and its bold phrases are the bullets. Bold the words you want to see, not the words you want to stress. A paragraph with no bold shows whole, in smaller type. A #### Title above a paragraph titles the card, and @12:30 on it is when you meant to reach it: the drift stands beside the clock.

Where the note stands is when it is said. A note before the first --- belongs to the beat the slide opens on, a note after it to the beat that --- opens. Open the speaker view on this chunk, press K, and walk it with Space: the cards under each diamond are the notes written under the matching --- in the source. A chunk whose notes all sit at the end shows them all on the first beat, so a lecture written before this feature does not move.

Single keys change how the lecture reads, and each one applies to both windows at once.

• C switches between what the audience sees and the full text.
• F cycles the font: serif, then sans, then monospace, for legibility across a room.
• A cycles the theme: four light ones with different accent colours, a neutral dark one, and two green-and-amber terminal ones.
• + - 0 set the text size; # cycles auto-fit through its three modes, which is worth trying right here – this chunk is longer than the screen.
• B blanks the projection.
• D puts a live demo on the projection: a window or a screen of this machine, chosen in a picker, until D again. The very first capture on a Mac fails while macOS asks for screen-recording rights – allow it and press D again, so do that once before the talk.
• L cycles the slide numbers: stacked, in a row, or off.

Shift with C, F, A or L goes backwards. # has three modes and no Shift, because it is a shifted key on some keyboards and an unshifted one on others. Font, theme and slide numbers are remembered for every lecture you open, so the preference follows you; zoom and the C setting are not remembered beyond the talk you are giving.

On a phone or a tablet with no keyboard, both windows show a small toolbar along the bottom edge. Forward, back, overview and zoom sit on it; C, F, A, #, the search and text selection are behind its ⋯ button. Attach a keyboard and the toolbar goes away again, because the keys are back.

Dark mode follows your machine unless something says otherwise. If you have never pressed A and the lecture pins no theme, a machine set to dark opens the lecture dark. Press A once and your choice is remembered from then on, everywhere. An author who writes theme: in the frontmatter overrides both, by the same rule as the other opening settings.

The two C modes keep separate zoom levels. The short version holds whatever size you set with + and -; the full text picks its own so the whole chunk fits the screen, and switching back restores yours exactly.

# cycles auto-fit through three modes, and the middle one, shrink, leaves your zoom where you set it and only makes a slide that is too big fit. So the audience reads one size all hour, except on the slides that would otherwise run off the bottom. Full sizes every slide to the screen, growing a short chunk as readily as shrinking a long one, which suits a lecture whose chunks vary a lot. Off is neither.

While the audience sees black, the speaker window keeps everything. The slide, the notes and the thumbnails stay where they were, so you can move on or read ahead with nothing showing. A small BLANK · hit B to toggle marker sits at the bottom of the speaker window, or at the bottom of the projection when there is no speaker window. D has the same shape: pressed in the speaker window, it opens the browser's picker there, and the window or screen you choose fills the projection while a DEMO · hit D to end it marker sits where the blank marker would. That is what a live demo on an extended desktop needs – the demo stays on the laptop, where the pointer is, and nothing has to be mirrored.

::: cols 2 (or cols 3) flows the body across that many columns, the way a newspaper page does. Use it when several short paragraphs read better side by side than stacked – a list of features, a brief comparison, two or three parallel definitions.

Columns fold to one while the slide is short – press C here and the two above stack. Shortened, each paragraph is down to its opening sentence, and a browser will not split a paragraph across columns, so two single sentences of different lengths do not balance. The full-text mode brings them back, and so do print.html and print-notes.html.

Revealed segments – the --- lines that uncover a chunk a piece at a time – work inside ::: cols, but text uncovered piecemeal while it also flows across columns is hard to follow: pick one or the other.

::: side makes two panes side by side, and ::: flip marks where one ends and the other begins. Unlike cols, you decide what goes where: everything before ::: flip is the left pane, everything after it the right. Use it for a figure with its commentary, or for a before-and-after pair.

Code in a pane needs short lines. A code block never wraps, so at the default zoom a pane holds about 36 characters against the 78 a block across the slide holds – and that 78 is the same whatever width the chunk is, because a code block of its own breaks out of the text column and spans the slide. A longer line is not cut off; the build shrinks that one slide until it fits, and the slide then reads noticeably smaller than the ones either side of it. Break the line, or put the code across the full width and keep the panes for prose.

::: marginalia sets an aside out to the right of the chunk, past the edge of the text column and into the slide's margin.

A marginalia is the one aside you can click: the frame slides right until all of it is on screen. A figure or a block of code opens in a card in the middle of the screen; a marginalia gets no card, because it is part of the slide's layout rather than something laid over it. Esc, or a click on the slide, moves the frame back. Try it on the block out to the right, the part of it the edge of the screen has cut off.

The body stays in the middle column and only the marginalia moves outward. Keep them short: a marginalia shares the chunk's height and cannot grow taller than it. One can also go inside a ::: side pane, when a tangent belongs to one half in particular – it still goes to the slide's right margin.

::: footnote puts a small grey note under the chunk, labelled and always visible – down in the flow of the text rather than out at the side. No button, no separate panel, nothing to click.

A marginalia goes out into the margin and can be brought to the centre with a click; a footnote stays under the chunk and is read where it stands. Use ::: footnote when the extra material is short and you want it on the page every time, and for ::: expand <label>, the chevron button from earlier, when it should stay behind a button until somebody asks.

Write ![Caption](fig-id) and the build looks in assets/ for fig-id.svg, .png, .jpg, .jpeg, .gif or .webp, taking the first it finds. No folder, no extension. Writing the path out in full still works when you need it.

As long as your pictures are small, the build puts them inside the HTML, so the whole lecture stays one file. The chevron has the limits, and what happens to a picture over them.

Drop clip.mp4 into assets/ and write ![](clip) – the same shorthand an image uses. The build looks for video files after image files, so an id that has both a still and a clip behind it gives you the still.

That player is a real clip embedded in this HTML file, a pan across the overview board. Press play, then check the address bar – nothing was fetched. The file is 78 KB and it costs 104 KB here, because a data: URI is base64 and base64 is a third larger than the bytes it carries – which is the price of the whole file being one file.

Play, pause and seeking are shared between the windows. Operate the clip at the lectern and the projection follows. Freeze the projection first and it does not, so you can check a clip before showing it.

A clip goes inside the HTML like any other asset, up to its own limit of 12 MB. A clip is an order of magnitude heavier than a diagram, and the 2 MB picture limit would reject every real one.

Over that limit the clip is stored beside the file instead. The build copies it into a videos/ folder next to the output, plays it from there, tells you on the terminal, and suggests an ffmpeg line that would make it small enough to go inside. One named folder to copy along with the HTML, instead of a path that only works on the machine that built it.

A clip can also live on a web server: ![](https://host/clip.mp4) works and stays an ordinary player, so play, pause and seeking are still synchronised between the two windows.

There is no fullscreen setting: the player has its own button, and how large the clip sits on the slide is the chunk's width, as with a still picture. Clicking a clip does not open it in a card either, because that would conflict with the play button.

A hosted player is written as ::: embed, and a bare link never becomes one. This is the only thing you can write that makes a lecture fetch from somebody else's server while you are teaching, so you say so in the source:

::: embed https://www.youtube.com/watch?v=aqz-KE-bpKQ
Big Buck Bunny, Blender Foundation
:::

The line under it becomes the caption. A youtu.be/… or a bare vimeo.com/123 works too; anything else has to be a full https:// address, and the build refuses what it does not recognise.

The address is always printed under the player, with a QR code on Shift-click, so people can reach the video even when the player will not run. YouTube is asked for through youtube-nocookie.com, and Vimeo is asked not to track.

A lecture with a hosted player no longer contains everything it needs: the machine showing it – often the lecture hall's own PC – contacts that company while you teach. A clip in assets/, or an .mp4 address on a server you control, keeps the two windows in step and needs no other server. The build tells you which of the two you have chosen.

• Nothing loads until you get there. The player points at the video only while its chunk is on screen.
• Play and pause are shared between the windows, as for a local clip. Freeze the projection and it stays put.
• Nothing starts by itself. Arriving at the slide gives you a loaded player waiting on its button.
• A player that cannot run is replaced by a card that says why. A page opened from disk has no web address and YouTube will not play; Vimeo does.

To teach with a YouTube video, serve the lecture:

node build.js <source.md> --serve         # prints the URLs
node build.js <source.md> --watch --serve # and live reload

Formulas are typeset when the lecture is built, so the finished file needs nothing at the moment you show it. Maths inside a sentence goes between single dollars – the anonymity set $S$ has size $|S|$ – and a formula on its own line goes between double ones:

A formula on its own line behaves like a figure: it stays on screen when the prose around it is shortened away, and clicking it opens it large for the audience.

This chunk carries {.blocks-left}, which is why the formula starts where this sentence starts. A code block, a figure and a display formula are centred by default, and style: {blocks: left} says otherwise for a whole deck. Centred is right when the block is the slide; on a slide that is an argument with a formula inside it, three blocks on three axes is what you get instead. Maths inside a sentence follows that sentence – on screen in an opening line, gone with everything else.

A lone dollar sign is safe. The delimiters are read as Markdown, not searched for in your text, so $PATH inside code, a price of $5 and $10 in prose, and a $$ inside a code block are all left alone. Write \$ if you want to be explicit.

Only the mathematical typefaces your formulas use are embedded in the file. The build prints what that came to: for this lecture, about 120 KB in each printed view and 166 KB in the projection, against the 254 KB a complete set of KaTeX faces would take.

The maths follows the F key. Switch the body font to sans or monospace and the formulas change with it instead of staying serif while the text around them changes. Only the letters change: operators, relations and brackets keep their own shapes, and a character the sans face does not have falls back to the mathematical one. That is where the projection's extra 46 KB goes – the printed document has no F key and carries no faces for it.

Most chunks that read badly on the projector fail in one of four ways.

All four read fine inside a paragraph and fall apart the moment the paragraph is taken away, so they show up when you walk the lecture once in the short view before you teach it.

When several parallel items pile up inside one paragraph, write a real Markdown list instead of scattering bold through the prose. A list stays readable when it is shortened; a paragraph with bold scattered through it almost never does.

A lecture can set its own starting look instead of inheriting whatever the reader last chose.

---
title: Anonymous Communication
font: mono              # serif | sans | mono
theme: terminal-green   # light-{red,teal,blue,orange}
                        # dark | terminal-{amber,green}
collapse: none          # topic-bold | none     – the C key
auto-fit: shrink        # true | false | shrink – the # key
slide-numbers: off      # vertical | horizontal | off
print-slide-numbers: vertical
                        # the same three. Left out, it follows
                        # whatever slide-numbers says
editor: speaker         # both | speaker | none – the diagram editor
---

lang: de                # the language the lecture is written in:
                        # en, de, de-DE, fr and so on, and en
                        # when you leave it out

lang: picks the hyphenation dictionary, and by default only the two printed views use it: a long German compound breaks at the end of a line there instead of leaving a hole, while the projection and the lectern view do not hyphenate. style: {hyphenate: all} puts it into the projection too, which a German lecture at .narrow usually wants, and none takes it out everywhere. It is not one of the six above in the other sense either – the six are opening settings that override whatever the reader last chose, and the language is a property of the lecture.

A key you write beats whatever the reader last chose, and a key you leave out leaves that choice alone. So a lecture that sets nothing behaves as before – font, theme and slide numbers follow the reader from lecture to lecture.

slide-numbers applies to print.html and print-notes.html too, and print-slide-numbers: overrides it there when the printed document wants different numbering from the projection. A value the tool does not know stops the build and lists the ones it does.

A ::: draw block is a figure written as text. The build draws it into the page: you name the boxes and say where each one goes, and the arrows between them are routed for you.

That drawing is these five lines and nothing else:

box src "Sender"
box mix "Mix"       right of src gap 2.1
box dst "Receiver"  right of mix gap 2.1
edge src -> mix "encrypted"
edge mix -> dst "recoded"

The first element sits at the origin, so a simple figure needs no coordinates. Everything after it is placed against a neighbour – right of, left of, above, below – and gap says how far. There is no automatic layout: an element goes where its neighbour and its gap put it.

Write step blocks and the figure changes with each forward press. One step is one press of the same key that uncovers a segment, so steps and segments arrive in the order you wrote them and the speaker view reads ahead exactly as it does for text. Press forward twice here.

The figure on the previous slide is the three boxes from the slide before it, with a logfile added and four lines at the end.

box  src  "Sender"
box  mix  "Mix"        right of src gap 1.05
box  dst  "Receiver"   right of mix gap 1.05
box  log  "Logfile"    below mix gap 0.9  {.dashed}
edge src -> mix "encrypted"
edge mix -> dst "recoded"
edge leak mix -> log {.dashed}
text why "this is where\nthe anonymity ends"  right of log gap 1.4 -- leak {.hand}
step leak
  show log
step blame
  emph leak, log

step leak shows the logfile, and step blame emphasises the leak and the box it runs to. The words a step knows are show, hide, move … to, move … by, the three attention verbs emph, dim and ghost, plus style and label.

Anything attached to something invisible is invisible too, which is why step leak names only the logfile. An arrow is only as visible as the two things it joins, a container or a brace only as visible as its members, and a text with a line drawn to something only as visible as what it points at. So showing the boxes shows the arrows between them, and most of a figure needs no show of its own.

A beat is taken in the order it was written, and that is wrong for one shape: a figure that steps in one pane and the words about it in the other. Written plainly the figure's steps come first and the words queue behind them, because document order is the only order there is. --- from N pins a beat to an advance by number instead, so the two halves move together.

A pinned beat rides one the slide already has rather than adding one, so this chunk takes two presses, not four. from 0 is refused – that is the beat the slide opens on, so write the words above the marker – and so is a from inside an ::: overlay from N or a ::: dock from N, which numbers its own markers already.

Every line in a ::: draw block has the same six slots, in this order, and most lines fill three or four of them:

box   mix   "Mix"   right of src gap 0.6   w 1.2    {.tone-2 @crypto}
kind  name  label   placement              options  tail

The name is how later lines refer to an element and is never drawn; the label is what the audience reads, and "" is a legal empty one. A name is letters, digits, _ and -, and a line starting with # is a comment.

Inside the tail, the first character says what a word is: . starts a class and @ starts a tag.

• .tone-2 is a class, which says how the element looks. {!tone-2}, with an exclamation mark, takes one off again.
• @crypto is a tag, which says what set the element belongs to.

A tag goes wherever a name goes, so show @crypto in a step selects every element that carries it. An element joins a set on its own line, which makes adding one a one-line edit.

Placement is a grid square, or a relation to a neighbour.

• at 2,1 puts an element in a grid square.
• right of mix gap 0.6 places it against a neighbour, as do left of, above and below.
• between a,b is the point on the line joining two elements.
• offset dx,dy is a nudge any of the three accepts on the end.

A coordinate can be another element's, plus or minus a little – at mix.cx,src.cy+0.4. Anywhere an X,Y pair goes, that form goes.

An anchor can carry a fraction: mix.right:0.3 slides the attachment point along that edge, so two arrows between the same pair of boxes run side by side rather than on top of each other. gap 0 flush left at the end of a placement makes two boxes touch.

An edge is one of the things a coordinate can name. text n "only after the handshake" above w1 gap 0.2 sets a phrase against the wire it describes rather than against a box at one end of it, so the label follows its line instead of drifting off it the next time a box changes height. Name the edge first, in the slot before the arrow's first end: edge w1 mix -> log. An edge has no name until you write one, and most edges never need one.

A picture can be an element too. image alice avatar-alice w 0.4 finds the file exactly as ![](fig-id) does, and an SVG drawing takes the theme's colours there in the same way.

Only one member of a group is in force. The names come from a fixed list, and {.tone-1} on a box therefore replaces a default box {.tone-4} rather than piling on top of it, which is what makes the groups worth knowing.

Three words put elements level with each other, and they are not interchangeable.

• flush finishes a placement and takes one word: below src gap 0 flush left keeps the new box's left edge level with src.
• align is a statement on a line of its own. align y middle a, b, c gives b and c the vertical centre of a; the first name is the one the others follow.
• spread x a, b, c, d shares a set out evenly. First and last stay put; everything between gets the same distance from its neighbours.

The two statements are both used in the sheet on the last slide: an align x right gives the five row labels the right edge of the first, and a spread x puts the five middle words of the family row between sans and bold.

Three statements draw data, and each turns into ordinary boxes, texts and edges first. bars becomes one box per column plus a baseline, grid one box per cell, and plot a frame of gridlines, ticks and two axis titles.

Everything a chart draws is an ordinary element with a generated name – wc-0, wc-1, … for the columns and ch-1-0, ch-4-2, … for the cells – which is why the brace and the tinted cells above needed no vocabulary of their own.

A second set of numbers is one more bars line: bars after "…" series of wc {.tone-1} joins the first chart's frame and borrows its ticks, its baseline and its scale. key "2024" on either line names the run, and the chart draws the legend itself.

horizontal lays the columns flat, which is what a chart wants as soon as its categories have names rather than numbers – lengths from one shared left edge are easier to rank, and “DNS cache poisoning” cannot be written under an upright column at all.

A plot draws the frame and the scale; you write the curves over it.

A chart is sized with aspect, not with w and h – those two are counted in grid squares, and a grid square is not square, so they do not describe the shape a reader sees.

A plot takes two ranges and one tick interval – after which pace@26 names a value in the plot's own units anywhere a coordinate can go, and the curves over it are ordinary edges.

A figure with steps is an argument in stages – the setting, the intruder, the cut wire, and what it costs. Press forward three times.

Every element after the first is placed against another one, so nothing comes apart when the middle box moves in. move eve to between alice,bob states a position, move alice by -0.5,0 shifts an element by an amount, and the whole figure is laid out again at every step – so Alice and Bob step aside, the container re-fits around them, and the arrows are drawn wherever their ends have gone. hide takes the direct wire away, dim is the opposite of emph, and label swaps in wording that was typeset when the lecture was built.

Two tags do all the revealing: @attack and @cut. show @attack brings Eve in and the handwritten caption with her, because both lines carry that tag; show @cut brings the three arrows through her a step later. The pair running to Bob leaves Eve's right edge at :0.2 and :0.8, a fraction along a side being how two arrows between the same two boxes run parallel instead of on top of each other, and side top and side bottom put one label above its line and the other below.

A figure written with autoplay advances its own steps on a timer once the slide is on screen – one delay, in milliseconds, for every step. A cover figure that moves while the audience files in is the case it was asked for, but it works on any chunk.

::: draw 150x56 autoplay 1200
box crawler "Crawler" {.tone-1}
box det "Detector" right of crawler gap 1.6
edge crawler -> det "request"

step probe
  emph det
:::

The timer presses the same key you would press, so the speaker view follows and freezing the projection stops it. It runs on the projection only, and the first key, click or scroll on that slide stops it – once you have touched the figure you have taken over. It also refuses to start on a slide that is already half uncovered.

The delay has to be between 200 ms and 60 s; outside that the build refuses the number rather than quietly moving it.

cycle repeats the run of steps – autoplay 1200 cycle – which is usually what a cover figure wants while the audience is arriving. It rewinds the same way it advanced, so the speaker view follows the rewind too. The last step is held for one delay like every other, and there is no second number for how long to hold the finished picture.

The figure below is running now, written exactly as the block on the slide before with cycle added. Press any key and it stops where it stands – that is the take-over, and it is why you can read the rest of this slide without it moving underneath you.

::: backdrop puts a picture behind the whole slide, edge to edge, and ::: overlay puts a block of text on top of it. One line each, on any chunk – a cover is not a special case. A backdrop names its picture the same three ways an image does: a bare asset id, a path, an https address.

## figure: {#skyline .full}

::: backdrop city-at-night {.invert .blur}

::: overlay {.bottom-left .ink .wide}
### Every endpoint is a sensor
A crawler that looks like a browser gets measured back.
:::

A backdrop's braces answer five questions, at most one word each. How the picture fills the frame – it covers the slide, or it fits inside it whole. Which part of it survives the crop. What is laid over it. Whether it is sharp or blurred. And whether it sits under the type or in front of it. Two words answering the same question is an error, and the message names both.

The default is veil: the theme's own paper at 80%, so ordinary dark text stays legible on a photograph in all seven themes. invert darkens the picture and turns the text light instead – the next slide is one.

An overlay answers three: where on a 3×3 grid, what it sits on (paper, ink, accent, clear or glass) and how wide. Every one is a card with padding and rounded corners, because text laid straight onto a photograph is unreadable at the back of a room.

The decoration lecture has a slide for each of the two lists, and a backdrop whose window opens on a keypress.

::: cards 3 puts three separate boxes across the slide, and an item sits in one of them whole and never spans two. A ::: cols 3 block does the other thing: one run of text the browser shares across three columns, so a paragraph can spill from the foot of one into the head of the next.

That row is one Markdown list between ::: cards 3 and :::, and each card has a second level folded away under it – press C and it appears. The folded level is in print.html and print-notes.html either way, so one row serves the audience and the hand-out.

One rule decides what becomes a card: write a single list and each of its items is a card; write anything else and each block is a card. The count runs from 1 to 6 – one card is a callout you want to stand apart, and past six what you have is a table.

How you open a card decides what the bold does, and the two below are written the two ways:

Use cols for an argument that runs long, and cards for a comparison the audience should be able to count.

Seven words in the tail set the look of a card row, written bare between braces, at most one per question – a second word answering a question already answered stops the build.

• ground – what the card is made of: a tint, a hairline, the page, or nothing.
• anchor – where the text sits when the card is taller than its content.
• corner, detail and scrim – the radius, the small print, and what is laid over a picture.
• size and align decide themselves: the longest item picks the size, and the alignment follows it.

ground is answered once for a whole row, so three grounds means three rows, each written ::: cards 1 {…} with its own word. panel is the default, a tinted fill; outline is a hairline and no fill; photo makes the card's first picture its background, and scrim says what is laid over it.

That row is ::: cards 3 {.outline .middle}, so its tail answers two questions at once: ground, and anchor – where the text sits when the card is taller than its content, which it always is, a grid row being as tall as its longest card.

::: rows is a card turned ninety degrees: a term in a card on the left, its explanation beside it, several of them stacked.

That row is ::: rows {.accent} around one list, and every term gets the same column width, so the explanations line up down the slide however long the terms are. The explanation is optional – a term written on its own is a labelled row with nothing beside it, which is what an agenda or a list of names wants.

It takes no count, a row block having one column by definition, and it takes every word a card row takes. Three defaults differ: the text is centred against its term rather than against its first line; align says how the term sits in its card, and the explanation always ranges left; and the automatic size stops at medium, a term being a label in a column rather than a headline across the slide.

Use rows when a term needs a sentence, and cards when a comparison needs counting.

The style: block holds the settings you make once for a whole lecture rather than chunk by chunk.

style:
  headings: left        # auto | left | center | off
  rules: off            # on | off  – the hairline over a principle
  labels: off           # on | off  – the type word over a chunk
  link-codes: off       # on | off  – the mark after an external link
  blocks: left          # center | left – where a code block,
                        # a figure and a formula sit
  wrap: none            # balance | none – even line lengths,
                        # in headings and in prose alike
  print-body: sans      # serif | sans – the printed document's face
  bold: accent-bold     # plain | bold | italic | accent | accent-bold
                        # | accent-italic – a **bold** phrase, live
  print-bold: italic    # the same six – a **bold** phrase on paper
  heading-scale: 1.15   # 0.6 … 1.8
  body-scale: 0.95      # 0.6 … 1.8

headings: auto is the default, and it means the type decides: a question is centred, a figure's caption sits over its artwork. left overrides all of that, for one line of alignment down the whole lecture. off takes every heading off the projection while keeping it in print.html, print-notes.html, the contents list and the search.

wrap applies to headings and prose both, which its name does not say: balance evens the line lengths of a heading and protects the last line of a paragraph, and none turns both off. blocks and wrap are the two keys a single chunk can answer for itself, with {.blocks-left} and {.wrap-none} in its attribute tail.

print-body is the one setting here that only the printed pages see. The projection and the lectern let a reader pick the face with F; a document has no reader to press it, so sans is how you ask for one set in the sans. Code stays in the monospace, and so does everything the document already draws in the sans – the type word, a caption, the contents list.

bold and print-bold set how a **bold** phrase looks, and plain is a legal answer because bold selects before it decorates. Live the default is plain, so a promoted bullet is set like the sentence above it; on paper it is bold, in the ink. accent-bold in both is how the tool drew every bold before the keys existed. A word stressed with *em* inside the phrase is bold and in the accent whatever the key says – except under accent-bold, where it stays italic.

The two scales multiply the tool's own sizes rather than replacing them, and they are bounded. Outside 0.6 to 1.8 the shortened view, the limit on how wide a line of code may be and the automatic zoom stop agreeing with each other.

The type word above a chunk is drawn in two places, and one setting takes it out of both.

style:
  labels: off

rules is the neighbouring key and switches the lines – the bar above a principle, the hairline above a definition. labels switches the words.

A figure's heading, set in capitals, is your own text and needs no key. It is the chunk's heading, drawn that way because the type is figure, so ## figure: {.wide #id} with no heading text leaves it off the slide. The cost is that the chunk then has no text for search to find and no heading in print.html. (The contents list is unaffected – T lists the lecture's columns, never its chunks.)

Three families are embedded in any one file, and you pick which three. Nine come with the tool, so naming one of those needs no font file at all.

fonts:
  serif: Bitter                    # or Literata, the default; also Source
                                   # Serif 4, Noto Serif, Roboto Serif
  sans: Inter Tight                # or IBM Plex Sans, the default
  mono: Noto Sans Mono Condensed   # or JetBrains Mono, the default

Only the three a lecture actually asks for are read, so choosing an alternative costs that lecture and no other. A name that is neither one of the nine nor a file in fonts/ stops the build, and the message lists the names available for that role.

Among the serifs, the question is what a projector does to a typeface. Bitter has the lowest stroke contrast and the smallest file, which is why it stays legible in a lit room; Roboto Serif has the strongest bold but sets 8% wider, so it re-wraps a deck written against another face.

The condensed monospace is 17% narrower – 0.50 em against 0.60 em per character, measured in a browser – so a listing that ran off the slide now fits. It is Noto Sans Mono with its width axis pinned rather than a different typeface, so it costs 54 KB. Slashed zero, and I, l and 1 are three visibly different shapes.

ligatures: decides whether letter pairs are drawn joined, and answers separately for prose and for code. text is the default: fi and fl joined up in prose, nothing joined in code. none takes them out of prose as well. all puts the code ones back, so JetBrains Mono draws -> as a single arrow again. The code ones are off by default because in the figure language -> and -- are two different arrows, and every listing on a slide is source somebody may retype.

A family that is not inside the file is a family the lecture-hall machine may not have. Safari does not tell a page which fonts a machine has, so a lecture that merely names one takes whatever that browser decides instead. The three a lecture carries are embedded in every output it writes, cost about 280 KB per file, and fonts: none leaves them out; the bundled three are under the SIL Open Font License, which permits exactly this.

Each of the three roles is answered on its own, so you can replace one and leave the others alone. Put your files in a fonts/ folder beside source.md:

fonts:
  serif: Vollkorn        # yours – the files are in fonts/
  mono: JetBrains Mono   # one of the five that ship, so no file
                         # sans: not written, so it stays the default

A file's name says which weight and style it is: Vollkorn-Regular.woff2, then -Bold, -Italic, -BoldItalic, -600, -600italic – or one file, Vollkorn[wght].woff2, carrying every weight. A family that is neither one of the five nor a file in fonts/ stops the build.

Putting a font inside the file redistributes it, so check the licence first. The SIL Open Font License and Apache-2.0 – between them nearly all of Google Fonts – allow that; most commercial desktop licences do not, and want a separate web licence. The build prints a reminder and checks nothing.

cover: in the frontmatter picks how the title slide is composed, and subtitle: gives it the line that says what the talk is about. Without those two, a cover is one weight of one colour with the subject set beside the venue, and it reads as a text file rather than as the opening of a talk.

title: How Caches Forget
subtitle: Eviction, Staleness and the Cost of Being Wrong
presenter: Jana Wieland
info: |
  Distributed Systems · Lecture 7 · Room WE5/00.019
  uni.example/ds
cover: split            # see the two rows below
cover-image: skyline    # only the four picture covers take one;
                        # on the six text-only ones it is an error

info: takes as many lines as you give it – the course and the room, the address students should write down, or, at a conference, its name and dates. Without subtitle: the one line saying what the talk is about has nowhere to go but info either, where it is set exactly like the rest.

They are ordered by how prominent the opening slide is. Six are text and nothing else:

Four take a picture:

beside, above and quote take their content from the chunk body, so a ::: draw can be the cover – a diagram is not a file, and cover-image can never name one.

The six text-only compositions each take a ::: backdrop, which is how a photograph reaches a cover with no cover-image of its own.

A column with a # Heading opens with a divider slide, and section: picks how that slide is drawn.

They stay less prominent than the cover, so that a divider is not mistaken for the title slide: it says a new part starts here, and it is part of the thing you are already in.

section: tinted         # plain | tinted | rule
                        # card | number | outline
section-mark: Teil      # any short word, or nothing

section-mark: puts a word of your own – Teil, Kapitel – over the heading. By default there is none.

## closing: draws a last slide in the same composition as the cover, so the lecture ends on the shape it opened with. A lecture that starts on a designed slide and ends on the last bullet of the last argument stops rather than finishes.

## closing: Questions? | office hours Thursday, 14–16 {#end}

Next week: certificates, and who you are actually trusting.

The heading is the first line, the sub-heading after the | is the second, and the body is whatever should stay on screen while the audience asks questions. Your name and the info block are not drawn.

A closing slide never uses cover-image by itself – ending on the opening picture unasked would be the repetition a closing slide is meant to avoid. closing-image: cover in the frontmatter asks for it, and the deck closes on the picture it opened with; any other value names a different one, in the same three forms cover-image takes. A ::: backdrop on the chunk is the other way and a different thing – a full-bleed ground behind the words, which works on all ten compositions and wins over both.