Slide recipes

Each recipe below is a complete section: the lines for script.md, the entry for cues.json, and the scene for deck/index.html. They use the stylesheet that decktalk init writes, so paste them into the scaffold and build. They are recipes rather than copies of the scaffold, whose own scenes are walked through in Your first deck. The scene and step ids are placeholders, and any section number works as long as the same number appears in the script heading, the [[section]] table, and the cues.json key.

Inside the backticks of a render template, write every backslash twice. The data-tex value \\frac{d}{dx} reaches KaTeX as \frac{d}{dx}, and a single backslash is swallowed by the template literal.

A subtitle that follows the voice

An element with data-sync reveals one word at a time, each at the second the voice reaches it, so a line on the slide keeps pace with the narration. The scaffold uses it for the subtitle of its title scene and for the three lines of its closing recap. The text must be word for word what the voice says, because the runtime matches it against the section’s spoken words, ignoring case and punctuation, and prefers the run nearest the cue. Give it data-fx="none", since a fade on the container fights the per-word reveal.

script.md

## 1. Open

Welcome. This is a narrated lesson, cut to the word. [beat] Every visual you see lands on
the word that introduces it.

## 5. Close

That is the whole idea. [beat] Write the script. [beat] Narrate it in your own voice.
[beat] And every reveal lands on its word.

cues.json

"1": { "cues": [
  { "cue": "1.1a", "on": "$start" },
  { "cue": "1.1b", "on": "This is" },
  { "cue": "1.1c", "on": "lands on the word" }
] },
"5": { "cues": [
  { "cue": "5.1", "on": "$start" },
  { "cue": "5.1a", "on": "Write the script" },
  { "cue": "5.1b", "on": "Narrate it" },
  { "cue": "5.1c", "on": "every reveal" }
] }

deck/index.html

DeckTalk.scene(1, { name: "Open", camera: "push", steps: [
  { id: "1.1", hold: 8, render: () => `
    <div class="slide">
      <h1 class="hero" data-cue="1.1a">My lesson</h1>
      <p class="line" data-cue="1.1b" data-sync data-fx="none">This is a narrated lesson, cut to the word.</p>
      <div class="lower" data-cue="1.1c" data-type="40" data-fx="fade">decktalk · scene 1</div>
    </div>` },
]});

DeckTalk.scene(5, { name: "Close", steps: [
  { id: "5.1", hold: 10, render: () => `
    <div class="slide">
      <p class="eyebrow">The whole idea</p>
      <p class="line" data-cue="5.1a" data-sync data-fx="none">Write the script.</p>
      <p class="line" data-cue="5.1b" data-sync data-fx="none">Narrate it in your own voice.</p>
      <p class="line" data-cue="5.1c" data-sync data-fx="none">Every reveal lands on its word.</p>
    </div>` },
]});

The cue mounts the line, and the words arrive from there. A line whose text differs from the script by one word reveals whole, and the recorder logs data-sync text not found in the spoken words. In a browser, ?scene=5 reveals each line whole, because the preview has no word times. The runtime reference has the rules.

A derivation that reveals line by line

This derivation is a recipe rather than a scaffold scene. Each line is its own element with its own cue, and data-display typesets it as display math. The answer uses pop so that it lands harder than the steps.

script.md

## 3. The derivative of x squared

Start with the definition of the derivative, the limit of a difference quotient. [beat]
Expand the square, and the x squared terms cancel. [beat] Only two x is left.

cues.json

"3": { "cues": [
  { "cue": "3.1a", "on": "definition" },
  { "cue": "3.1b", "on": "Expand" },
  { "cue": "3.1c", "on": "Only two x", "offset": 0.2 }
] }

deck/index.html

DeckTalk.scene(3, { name: "The derivative of x squared", steps: [
  { id: "3.1", hold: 14, cues: { "3.1a": 1, "3.1b": 5, "3.1c": 9 }, render: () => `
    <div class="slide">
      <p class="math" data-cue="3.1a" data-display
         data-tex="\\frac{d}{dx}\\,x^2 = \\lim_{h \\to 0} \\frac{(x+h)^2 - x^2}{h}">d/dx x^2 = lim (x+h)^2 - x^2 / h</p>
      <p class="math" data-cue="3.1b" data-display
         data-tex="= \\lim_{h \\to 0} \\frac{2xh + h^2}{h} = \\lim_{h \\to 0} (2x + h)">= lim (2xh + h^2) / h = lim (2x + h)</p>
      <p class="math answer" data-cue="3.1c" data-fx="pop" data-display
         data-tex="\\frac{d}{dx}\\,x^2 = 2x">d/dx x^2 = 2x</p>
    </div>` },
]});

The plain text inside each element is what shows when KaTeX is absent, so write it as a readable fallback.

A chat before and after

The question types in with data-type, and the reply fades in one line at a time. The bubble and its first line share a cue, so the bubble’s background appears at once while the text arrives. The second step is the “after”, and its cue 4.2 mounts it. The scaffold’s own before-and-after scene syncs each prompt to the voice with data-sync instead, which suits a prompt the narrator reads aloud.

script.md

## 4. Before and after

Watch a vague prompt first. [beat] Write about photosynthesis. [beat] The reply is true,
and it is flat. [beat] One line says what it is. [beat] Another line says where it happens.

[Step 4.2.]

Now ask for what you actually want. [beat] Explain it to a ninth grader, in three
sentences. [beat] Same model, better prompt.

cues.json

"4": { "cues": [
  { "cue": "4.1ask", "on": "Write about" },
  { "cue": "4.1r1", "on": "One line" },
  { "cue": "4.1r2", "on": "another line" },
  { "cue": "4.2", "on": "Now ask" },
  { "cue": "4.2ask", "on": "Explain it" },
  { "cue": "4.2reply", "on": "Same model" }
] }

deck/index.html

DeckTalk.scene(4, { name: "Before and after", steps: [
  { id: "4.1", hold: 12, cues: { "4.1ask": 1, "4.1r1": 5, "4.1r2": 7 }, render: () => `
    <div class="slide">
      <p class="eyebrow">Before</p>
      <div class="chat">
        <div class="bubble ask" data-cue="4.1ask" data-type="40" data-fx="fade">Write about photosynthesis.</div>
        <div class="bubble reply" data-cue="4.1r1" data-fx="fade">
          <p data-cue="4.1r1" data-fx="fade">Photosynthesis is the process by which plants convert light into energy.</p>
          <p data-cue="4.1r2" data-fx="fade">It takes place in the chloroplasts.</p>
        </div>
      </div>
    </div>` },
  { id: "4.2", hold: 12, cues: { "4.2ask": 1, "4.2reply": 6 }, render: () => `
    <div class="slide">
      <p class="eyebrow">After</p>
      <div class="chat">
        <div class="bubble ask" data-cue="4.2ask" data-type="30" data-fx="fade">Explain photosynthesis to a ninth grader in three sentences.</div>
        <div class="bubble reply" data-cue="4.2reply" data-fx="pop">
          <p>Plants catch sunlight and use it to turn water and air into sugar.</p>
        </div>
      </div>
    </div>` },
]});

A code block that reveals one line per phrase

Each line is a block element with its own cue. A container with white-space: pre and a monospace font keeps the indentation, and fade avoids the vertical motion of rise, which looks wrong on code.

script.md

## 5. Three commands

Three commands run the whole thing. [beat] Initialize a project. [beat] Build it
silently, with no key. [beat] Then build it with your voice.

cues.json

"5": { "cues": [
  { "cue": "5.1a", "on": "Initialize" },
  { "cue": "5.1b", "on": "silently" },
  { "cue": "5.1c", "on": "your voice" }
] }

deck/index.html

<style>
  .code { font: 40px/1.5 ui-monospace, Menlo, monospace; white-space: pre; background: var(--surface); border-radius: 24px; padding: 40px 56px; }
  .code .cmt { color: var(--muted); }
</style>
<script>
DeckTalk.scene(5, { name: "Three commands", steps: [
  { id: "5.1", hold: 10, cues: { "5.1a": 1, "5.1b": 4, "5.1c": 7 }, render: () => `
    <div class="slide">
      <div class="code"><div data-cue="5.1a" data-fx="fade">decktalk init my-lesson</div><div data-cue="5.1b" data-fx="fade">decktalk build --silent   <span class="cmt"># no key</span></div><div data-cue="5.1c" data-fx="fade">decktalk build</div></div>
    </div>` },
]});
</script>

Keep the lines on one physical line inside the render template, because white-space: pre would otherwise render the template’s own indentation.

A two-column comparison

Two columns, each with a heading and a caption, revealed left then right. The flex cols class from the scaffold lays them out, and each column gets one cue.

script.md

## 6. Two ways to time a reveal

On the left, a timeline. Every reveal is a number of seconds, and every edit moves them
by hand. [beat] On the right, the words. Every reveal is a phrase, and it follows the
sentence wherever it goes.

cues.json

"6": { "cues": [
  { "cue": "6.1left", "on": "a timeline" },
  { "cue": "6.1right", "on": "the words" }
] }

deck/index.html

<style>
  .col { flex: 1; background: var(--surface); border-radius: 24px; padding: 48px; min-height: 520px; }
  .col h2 { font-size: 56px; margin: 0 0 24px; }
</style>
<script>
DeckTalk.scene(6, { name: "Two ways to time a reveal", steps: [
  { id: "6.1", hold: 12, cues: { "6.1left": 1, "6.1right": 6 }, render: () => `
    <div class="slide">
      <div class="cols">
        <div class="col" data-cue="6.1left">
          <h2>A timeline</h2>
          <p class="line">Every reveal is a number of seconds.</p>
          <p class="caption">Every edit moves them by hand.</p>
        </div>
        <div class="col" data-cue="6.1right">
          <h2 class="accent">The words</h2>
          <p class="line">Every reveal is a phrase.</p>
          <p class="caption">It follows the sentence wherever it goes.</p>
        </div>
      </div>
    </div>` },
]});
</script>

A screenshot slide that waits for the image

The recorder starts the narration clock only after window.__sceneReady resolves, so a page with a large image should set that promise to the image’s decode. Set it in a script that runs before the runtime starts, because the runtime sets its own promise only when the page has not. The image is decoded into the browser’s cache, so the img element inside the step appears at once when its cue fires.

script.md

## 7. The status report

Here is the status report after a build. [beat] Every section shows a recording and a
cut, and the captions and chapters sit beside the video.

cues.json

"7": { "cues": [
  { "cue": "7.1shot", "on": "status report" },
  { "cue": "7.1note", "on": "captions" }
] }

deck/index.html

<style>
  .shot { width: 1600px; border-radius: 16px; box-shadow: 0 24px 80px rgba(0,0,0,.5); }
</style>
<script src="decktalk-runtime.js"></script>
<script>
const shot = new Image();
shot.src = "../media/status.png";
window.__sceneReady = document.fonts.ready.then(() => shot.decode()).catch(() => {});

DeckTalk.scene(7, { name: "The status report", steps: [
  { id: "7.1", hold: 10, cues: { "7.1shot": 0.5, "7.1note": 5 }, render: () => `
    <div class="slide">
      <img class="shot" src="../media/status.png" alt="" data-cue="7.1shot" data-fx="fade">
      <p class="caption" data-cue="7.1note">Captions and chapters sit beside the video.</p>
    </div>` },
]});
</script>

A page that sets its own __sceneReady and also uses data-tex should wait for window.katex itself, because the runtime’s KaTeX wait is part of the promise it would otherwise have set. The runtime reference has the details.

The page contract has the sizes and margins that keep text readable at 1920 by 1080, and a table of which reveal effect suits which element.

Get started

Guides

Concepts

Reference

Help

A subtitle that follows the voice

A derivation that reveals line by line

A chat before and after

A code block that reveals one line per phrase

A two-column comparison

A screenshot slide that waits for the image

Next

​A subtitle that follows the voice

​A derivation that reveals line by line

​A chat before and after

​A code block that reveals one line per phrase

​A two-column comparison

​A screenshot slide that waits for the image

​Next

A subtitle that follows the voice

A derivation that reveals line by line

A chat before and after

A code block that reveals one line per phrase

A two-column comparison

A screenshot slide that waits for the image

Next