Writing scripts

A script is markdown. The prompter reads a small, deliberate subset of it — four marks that mean something about delivery, and a heading that divides the script into sections.

The four marks

These are the product, not decoration. The colours are consistent everywhere, so reading them becomes a skill you build while presenting.

• **bold**Vocal stress. Punch this word.

  One to three per slide. Everything emphasised is nothing emphasised.

• *italic*A wry aside, a tone shift.

  One or two per slide.

• `code`An identifier, read as a token.

  Lets you write the real symbol instead of spelling it out.

• "quoted"Something a real person actually said.

  Only for real quotes. Wrap the complete quote, not just its tail.

Sections and slides

A [SLIDE NN — label] heading starts a new section. Crossing that heading broadcasts the slide number to a deck listening on the same browser, so ordinary slide changes need no tokens at all.

[SLIDE 01 — title]

Hello world, and here's what happened this week.

[SLIDE 02 — the first story]

Voting opened on Friday.

A script with no headings at all still works — it scrolls as one section and simply drives no deck.

Chapters and named slides

A [CHAPTER Name | flags] heading is the other way to start a section, and the one to reach for when a show is bigger than its deck. Entering a chapter logs a chapter cue with its name — exactly what a hand-placed Marker::chapter token used to log — and moves no slide. Inside a chapter, only Slides:: tokens change what the deck shows, so a chapter can run three slides in ten seconds or hold one for a minute.

[CHAPTER Cold Open]

<|Slides::goto: identifier-rule|> Two variables that look identical aren't.

[CHAPTER Strict Identifiers | short]

<|Bumper::top_story|> <|Slides::goto: identifier-rule|> It starts with a rule most of us never read.

So the survey was rerun. <|Slides::goto: survey|> Half a million files.

Anything after a | in the heading is a flag. Flags mean nothing to the prompter; each one is logged verbatim as a chapter-flag cue right after the chapter cue, so the edit can find every chapter marked short without reading the script. A flag may carry an argument after a colon, kept as written. Flags describe the chapter; anything that appears in the video — a chapter card, say — is a token placed in the dialogue where it happens, like <|Bumper::top_story|> above.

A Slides::goto may name a slide instead of numbering it. Names resolve in order of first use — the first name the script mentions is slide 1, the second is slide 2 — which is the order a deck exported from the same draft is numbered in. A name the script never introduced moves nothing, on purpose. Naming slides is what lets you rewind to survey for a retake without counting.

Both heading forms can share a script. A chapter never repeats a slide number, so the numbering warning above cannot fire for it; the prompter warns instead when a chapter name repeats.

Why word count matters

Scroll speed is derived from each section's own density rather than a fixed pixel rate, so 140 words per minute means the same reading pace in a sparse section and a dense one. Markup characters and control tokens are excluded from the count — they are never spoken, so they must not push the scroll along.

The practical consequence: don't pad a script with anything you won't say. Pronunciation notes in particular belong somewhere else.