Ten ways to open a lecture

cover: in the frontmatter picks one of the ten below, ordered by how loudly the opening slide announces itself rather than alphabetically.

A name and a sentence carry the idea; they do not carry the shape it makes. Each of the ten is shot from a real build in the gallery.

Three keys the cover reads

cover-image: names the picture, and four of the ten draw one: split, hero, beside and above. On the last two it is only the fallback – they take whatever you write under the ## title: heading, so a ::: draw can be the cover.

cover-ratio: is how much of the slide the picture takes, as a percentage between 15 and 75. Only the three that divide the slide read it – split, beside and above. A percentage and not a W:H ratio: the shape of the frame comes from the projector, and this splits it.

cover-align: puts the block of text at the top, the middle or the bottom. The seven compositions that leave the block any freedom read it.

Set either of the last two keys on a composition that has already settled the question and the build stops with an error rather than ignoring the line.

The last slide closes the arc

## closing: draws the last slide in whatever composition cover: names, so the room sees the shape the lecture opened with.

What it carries is different: your own heading, sub-heading and text, and neither the presenter line nor the info block – the room learned who is talking and where an hour ago. The last slide of this lecture is one.

Six treatments, every one quieter than the cover

A divider has one job: to say that a new part starts here, and that it is part of the thing you are already in. One that can be mistaken for the title slide has failed at it.

The six are in the same gallery as the covers, under the same rule: a deck settles on one and wears it at every part.

The lines under a # heading are the divider's slide

Whatever you write between a # Heading and the first ## heading under it becomes the divider's slide. Ordinary markdown is the words, a ::: backdrop is the picture, a ::: draw is the figure.

Those three are what a divider takes; the other directives belong inside a ## slide. The words do print, as a short paragraph under the part title. The divider slide itself never prints.

::: cards makes boxes, not columns

::: cards 3 puts three boxes side by side, and an item is whole or it is nowhere. ::: cols 3 is the other thing: one flow of text the browser balances across three columns, so a paragraph can spill from the foot of one into the head of the next. Use cards for three things, columns for one long argument.

What a card sits on

The ground word says what is behind the text, and a row wears one at a time: these two are set to accent and to the default panel, whatever their cards say. outline is on the slide before this one, and corner is a separate question.

The row size reads the longest item

size: auto counts the words in the longest card: three or fewer sets the row large, twelve or fewer medium, more than twelve small. One size for the whole row, never one per card.

Alignment then follows the size, a single word centring and a sentence ranging left. A row that carries a second level ranges left whatever its heads measure, so the heads do not jump when the reader presses C.

One row serves two views

detail: fold is the default, so the levels under the first are in the printed hand-out and off the projection, and C switches between the two. This deck opens with everything showing, because its frontmatter says collapse: none; press C once here and the second level folds away.

::: rows turns a card row on its side

A term in a small card on the left, its explanation beside it, several stacked. It takes the same words in braces as ::: cards, the same automatic size, the same fold and the same print rules. Only the arrangement of an item differs.

Every term gets the same column width, so the explanations line up down the slide however long the terms are.

::: side takes a ratio

The window walks the beats, and the picture stands still

::: backdrop dusk {.cover} reveal full, right 52% gives the picture one place per beat – one press of Space – and the last place stays. Two moves come out of it: a picture that retreats to free the space the words need, and one that grows over the words and covers them.

What moves is the window, not the picture. The photograph is painted across the whole slide either way and the frame opens and closes over it, so nothing zooms or slides about while it is being revealed.

from holds an overlay back until a beat

::: overlay {…} from 1 keeps the block off the slide until the first press of Space. One number, not a list: an overlay is either on the slide or it is not, where the backdrop's list says where the picture is at each beat.

An overlay and a reveal segment both fade in, and neither moves anything: the segment has its box in the text from the first beat, and the overlay has its cell over the picture. What from adds is the number - a segment takes the next beat in order unless it is written --- from N, where an overlay says which beat it waits for and nothing else can reach it first.

Where the picture sits, and what it is veiled with

Five groups of words go in the braces after ::: backdrop, at most one from each, and the first of every group is the default.

veil puts the theme's own page colour over the picture, not white, so ordinary text stays readable on a photograph in all seven themes. invert darkens the picture and turns the text light instead, which is what the divider at the start of Part 2 does.

An overlay is a block of text over the slide

Nine places, five backgrounds, four widths, two shapes. Aim two overlays at the same corner and they stack rather than landing on top of each other. A panel is the card grown to the frame - the next part shows the three compositions - and third / half are a band's height.

A dock is part of the frame, and the text yields to it

An overlay lies over the slide; a dock takes its room from it. The list on the left is one ::: dock {.left .every} written under this part's # heading, and every chunk of the part carries it - the item the room is on lights up, because each entry is a link to a chunk's {#id}.

Four edges, the overlay's grounds, three widths. A left or right dock is a column the full height of the slide and the text column narrows beside it; a top or bottom dock is a band across the whole width and the text sits above or below it. A chunk that writes its own ::: dock replaces the inherited one for that slide.

The text column narrows, and two columns still fit beside a dock

A .wide chunk keeps ::: cols 2 beside the inherited dock. The chunk reserves the dock's track as padding, so the content column is what the slide leaves - and the linter says when that falls under the measure (dock-narrows-measure) or under what a column needs (layout-too-narrow).

A band replaces the inherited column

This chunk writes ::: dock {.bottom .accent .third} of its own, so the part's list steps aside for one slide and a band a third of the slide high carries the line under the words.

A band at the head, and the chrome moves to the foot

::: dock {.top .accent} is a line above the words, as wide as the slide and as tall as its own text. The slide number and the note button, which live at the head, move to the foot under it.

A dock held to a beat arrives into a track kept free

from 2 holds this remark back until the second beat. The text column has been narrow from the start, so nothing moves when the dock slides in - the rule an overlay card follows, kept here because a slide that reflows under the room's eyes reads as a fault.

The first beat shows this line.

The second brings the dock.

The dock's words

Four edges, six grounds, three widths, three heights, two scopes. One dock per slide; a #id link in the body is the live marker.

Six beats in source order, and nothing moves

A --- inside a pane, a card row or a dock is a beat on the slide's own counter. Left one, left two, right one, right two, then the card row, then its third card - the order they were written in, top-level and nested mixed.

Rows that arrive one at a time

A --- between two rows shows the second on the next press, and the first does not move: the block is laid out with both rows from beat 0.

{.bare} gives up the projection and nothing else

{.bare} keeps a heading out of the projection and leaves it everywhere else. Writing no heading would cost the slide, the printed document and the search index together; a talk that is a run of figures with speaker notes usually wants to lose only the first.

So ## figure: How a crawl is scored {.full #id .bare} prints the heading, indexes it, and draws nothing on screen. style: {headings: off} says the same for a whole deck. Press / and search for measurement loop: it matches this slide and the next one, and the next one carries no heading on screen.

The two revealed photographs in Part 4 are the case the class was written for: each is a picture and a speaker note, each would have read wrong with a line of type above it, and each is still a row in the search index.