This deck is one Markdown file. Every slide shows the Markdown that produced it.
Part one
#, ## and --- are what decide where a slide begins. Everything else in the file is ordinary Markdown.
The whole workflow
Nothing to install and no project to set up. Below is what the two commands printed when this deck was built from examples/tutorial.md.
$ node tools/md-to-deck.mjs examples/tutorial.md -o examples/tutorial.html
md-to-deck: 17 slides -> examples/tutorial.html
12 98 % directive:cols--2 Old against new, do against avoid
9~ 66 % gap 21 % directive:cols--2 A two-column table becomes a timeline
typography: 9 marks normalised
$ tools/build-deck.sh examples/tutorial.html
0.02 MB linked -> 0.13 MB self-contained
no external references: opens with no server and no network.md stays the source of truth. Re-running the converter overwrites the HTML, so hand-tune only once you have stopped converting.Structure
This file has four # headings after the title. Each one becomes a numbered divider slide, and the four of them together are the contents list on the title slide – hover the link and count them.
# How to write a briefing ← title slide
# The document ← divider, numbered 1
## Where slides begin ← a content slide
{eyebrow="Structure"} ← optional attributes
--- ← a break, for a slide
with no headingA heading may take one {…} line under it. {#anchor} gives the slide an id so another slide can link to it, {eyebrow="…"} puts a small line above the title, {.center} centres the content, {keep} leaves this slide’s layout untouched.
Part two
The converter reads the structure of your Markdown and picks a component for each slide. It also adjusts what you wrote: more columns or fewer, or an overfull prose slide split into two. It never invents text to fill a gap, and every slide it could not fix is named in the report it prints.
Four ### blocks at the same level become a bordered 2×2 grid. Two become two columns, three become three, and five to eight become two columns of stacked cards.
### Candidates
They sit the exam.
### Examiner
Owns the paper.
### Invigilators
They set up and watch.
### Technical lead
Knows the system.They sit the exam.
Owns the paper.
They set up and watch.
Knows the system.
A > blockquote becomes the highlighted band across the bottom of the slide. It can sit anywhere in the slide’s source, first block or last, and still ends up down there.
> Who leads is settled **before**
> the exam day.
Three roles, one rule: whoever
leads is settled before the day.Three roles, one rule: whoever leads is settled before the day.
The quotation went to the band at the foot of the slide, although it was written above this column.
A short list in which every item reads **value** – label, and the value contains a digit, comes out as a row of figures. The first item is set largest, so lead with the number you most want read.
- **1280** – commits across the project
- **11** – weeks from kickoff to launch
- **3** – people, none of them full timeA table of two columns becomes this label-and-text list. You set no widths anywhere: the label column on the left comes out as wide as its longest label, and no wider. A table of three or more columns stays an ordinary table instead.
| When | What happens |
| --- | --- |
| The evening before | Laptops imaged |
| −45 min | Room open, laptops out |
| −10 min | Doors closed, IDs checked |
| 0 | Exam starts |
| +90 min | Working time ends |Part three
Some layouts cannot be read off Markdown, so you name them with a directive: ::: name on its own line, the blocks that belong to it below, then ::: to close. Five directives appear in this part; the rest of the catalog works the same way.
::: editorial
::: editorial gives the first ### block a large panel of its own and stacks the others beside it as smaller cards. Use it when one point carries the slide. Markdown has no way to show that one of five blocks outranks the others, which is why this layout has to be asked for by name.
::: editorial
### The one thing that mattered
Everything else followed from it.
### A smaller lesson
Worth a line.
### Another
Also worth a line.
:::Everything else followed from it.
Worth a line.
Also worth a line.
::: delta · ::: principles
::: delta puts an arrow between the two halves of each item. ::: principles sets two bullet lists side by side, each under its own heading. Both bodies are plain Markdown lists.
::: delta
- Seven pages -> **One guided flow**
- A PDF by e-mail -> **A link**
:::
::: principles
### Do
- Cite the source
- Say what changed
### Avoid
- One line per slide
:::::: chart
The six bullet lines on the left produced the chart on the right. max=220 sets the top of the scale the bars are measured against, values prints each number above its bar, and the bars take the theme’s accent colour, the same one as the heading above them.
::: chart max=220 values label="Commits per week"
- W1: 40
- W2: 95
- W3: 120
- W4: 60
- W5: 150
- W6: 205
:::No directive needed
A numbered list whose items start with a bold phrase becomes numbered steps, in two columns once there are four. Nothing to name here: the numbering already says what these are.
1. **Absprache** Agree room and
laptop count.
2. **Aufbau** Lay out machines,
check network.
3. **Einlass** Doors close, IDs
checked.
4. **Abbau** Pack down, count
papers twice.Agree room and laptop count.
Lay out machines, check network.
Doors close, IDs checked.
Pack down, count papers twice.
::: detail
::: detail adds a clickable strip along the bottom of a slide, and clicking it covers the slide with a full panel. Put a derivation or the numbers behind a claim in there. The reader who wants that much can open it, and the reader who does not is never held up by it.
::: detail line="**How this panel was made.**" more="Show the method"
## What a reveal is made of
### The strip
What `line` and `more` write on it.
### The panel
Laid out exactly like a slide.
:::The Markdown beside this paragraph is what produced it, with the two panel texts shortened and the closing quotation left out. Click the strip and read what opens.
line="…" is the text on the strip itself: say what is behind it rather than “click here”. more="…" labels the button on its right, and eyebrow="…" works as it does on a slide.
Everything after the leading ## is laid out exactly like a slide. The two panels you are reading are two ### blocks, and the band below them is a > blockquote. This panel has no page number and no navigation dot, so paging from slide to slide never lands on it.
Part four
Limits
Material already written as a document: a retrospective, project documentation, a research summary, lecture notes, a report with numbers in it. Such a source arrives with its own sections and comparisons, and the job is getting all of them onto slides without dropping any of it on the way.
A spoken keynote of one line per slide, where the timing and the order of question and answer carry the talk. That was tried on a real one. Filling the slides worked against the timing, and keeping them sparse gave a deck of near-empty frames. For that kind of talk the pacing is the design, and no converter can supply it.
No animation beyond the click-to-open panels. No speaker view, no presenter notes on a second screen, no .pptx export. Charts are bars and nothing else, and the only image effects are a lightbox and a fanned stack.
This deck is designed for landscape. Rotate your device, or tap to dismiss.