Writing scripts

The Markdown you can use, how a script is broken into blocks, and cues.

Scripts are blocks

Before anything is rendered, a script is split into a flat list of blocks: a heading is a block, a paragraph is a block, each list item is its own block, a blockquote is a block, a table is a block.

Blocks are the coordinate system the two devices share. When your phone says “we are a third of the way through block 42”, the display resolves that to its own pixel offset. It is also what the remote’s previous and next buttons step through.

Practically, that means how you break up the text changes how the remote behaves. A wall of text is one block, so stepping jumps a long way. Four bullets are four blocks, so stepping moves one beat at a time.

Supported syntax

The editor is Markdown with GitHub extensions. Everything below is understood by both the editor preview and the prompter:

Syntax	Becomes
`# Title` … `###### Six`	A heading block, set slightly larger and heavier.
Plain lines	One paragraph block per run of non-blank lines.
`- item` or `1. item`	One block per item, with the marker set small and dim.
`> quote`	An indented block with a rule down the left.
`bold`, `italic`, `code`	Inline emphasis, applied inside a block.
`[text](url)`	Underlined text. Links are never clickable on the prompter: a stray tap mid-take should not open a browser.
A table	One block, rendered small. You do not read a table aloud line by line.
``` fenced code	One block, monospaced, excluded from the word count.

Cues

A line that begins with two colons is a cue, a direction to yourself rather than something you say:

Thank you all for coming.

:: pause, wait for the room to settle

There is one thing I want to leave you with.

Cues are:

set in the accent colour, small and uppercase, so they never read as script;
excluded from the word count, and therefore from the timing;
still blocks, so the remote can step onto one and hold there.

There is a toolbar button for them in the editor, and it wraps whatever you have selected.

Why two colons

HTML comments and blockquotes both already mean something in Markdown, and both survive copy-paste into other tools in confusing ways. Two colons at the start of a line mean nothing in standard Markdown, so a script with cues still reads correctly if it is opened somewhere else.

Breaks and sections

--- on its own line becomes a visible break on the prompter: a thin rule with the word break in the middle. Use it between segments so you can see one coming.

Headings do the same job with a name attached. The editor sidebar counts them, and they are what you will scan for on the remote when you need to jump somewhere.

Words, pace and timing

The word count excludes cues, code and table markup; it is meant to be the number of words you will actually say. The estimate in the sidebar uses 130 words per minute, which is a measured speaking pace, not a reading pace.

During a session, speed is set in words per minute rather than pixels per second. Teleprompt converts it using the measured height of your script and its word count, so 130 wpm on a phone and 130 wpm on a 27-inch display are the same delivery speed. Change the type size mid-take and the pace does not change with it.

Writing for the ear

A few things that consistently make a script easier to read out loud:

One idea per block. Short paragraphs give you natural places to breathe and give the remote somewhere useful to step to.
Write contractions. If you would say “we’ve”, write it that way; reading “we have” out loud sounds stiff.
Put numbers in words when they are hard to say. “Twenty-eighteen” reads more reliably than “2018” at speed.
Mark the landings. A cue before your closing line is worth more than a rehearsal.

When the script is ready, the remote covers what to do with it.