Skip to main content
This guide writes one section of a deck in the four files you write. Use it after the quickstart, when you are ready to make a section of your own. The section is a short lesson on gradient descent. Its slide draws a bowl in SVG and typesets the update rule with KaTeX.

​
Before you start

Start from the scaffold, and remove its section 3.
  1. Create a project with decktalk init my-lesson. The scaffold puts the runtime and KaTeX in deck/.
  2. Go into the project with cd my-lesson.
  3. In script.md, delete the text from ## 3. How AI learns up to ## 4. The edit.
  4. In decktalk.toml, delete the [[section]] table that has number = 3.
  5. In cues.json, delete the "3" entry.
Keep deck/index.html. It has scenes 1, 2, 4, 6, 7, and 5, and no scene 3. The steps below add a new section 3 that plays on deck/index.html instead of deck/lesson.html. Register each scene number only one time in a page. A second DeckTalk.scene(3, …) replaces the first, and no warning appears.

​
How the four files connect

One section number and one cue id tie the four files together. The narrate stage also writes a words file for the section, with the start and end of every spoken word. The beats stage matches each cue phrase against those spoken words.

​
Write the section

1

Add the script to script.md

Paste this section into script.md, between section 2 and section 4.
script.md
Each ## N. Title heading starts a section. The voice does not speak text in square brackets. [beat] makes a short pause, and [pause 3] asks the voice for three seconds of silence. script.md lists every rule.
2

Add the section to decktalk.toml

Paste this table between the section 2 and section 4 tables.
decktalk.toml
Every script section needs one [[section]] table with the same number. page names the page, and scene names the scene that the page plays. decktalk.toml lists every key.
3

Add the cues to cues.json

Add this entry under "sections".
cues.json
Each reveal starts on one phrase:
  • The bowl draws on “loss surface”.
  • Each move of the point starts on the phrase that names it, such as “take a step”.
  • The update rule appears on “learning rate”.
  • The overshoot path draws on “overshoot”.
  • The settled point appears 0.2 s after the start of “settle”, because its offset key is 0.2.
The 3.1 cue on $start only mounts the step at 0.0 s, so decktalk verify skips it as REFERENCE_CLAMPED. If the speech is shorter than min_seconds, decktalk beats reports an uncertain finding. Cues explains how phrases match.
4

Add the scene to deck/index.html

Paste the <style> and <script> blocks just before </body> in deck/index.html.
Write every backslash twice inside a render template. A single backslash breaks a data-tex equation or blanks the page.
deck/index.html
  • A scene is a list of steps, and each step renders one slide. Step 3.1 owns every cue here, because its cues object names each one.
  • An element with data-cue stays hidden until its cue fires. data-fx picks its reveal effect.
  • The bowl path has pathLength="1" and data-fx="draw", so its stroke draws over data-dur (1.6 s).
  • KaTeX typesets the data-tex element. The plain text inside the element is the fallback.
The scene brings its own CSS, because the scaffold’s stylesheet styles only its own classes. Runtime lists every attribute.

​
Look before you build

Check the slide in a browser and in screenshots before you record it. Browser preview and recording says which page values a browser preview uses and which values the recording uses.
  1. Open deck/index.html?step=3.1 in a browser. The step mounts with every element visible.
  2. Open deck/index.html?scene=3&hud=1. The scene plays in autoplay, with the clock on top.
  3. Take a screenshot of every step with decktalk shots. The PNG files go under build/shots/.
  4. Estimate every reveal with decktalk preflight. It freezes the page before and at each cue, and flags a reveal too small for verify as THIN CHANGE? or NO CHANGE.
If the project has no voiced build yet, you can also check where each cue phrase resolves. On a voiced project, a silent narrate stops, because it would empty the narration cache. Skip these actions there.
  1. Write estimated word times with decktalk narrate --silent.
  2. Print each cue time with decktalk beats.
Each entry reads cue id@cue time, in seconds after the section start. If a phrase is not in the spoken words, beats prints phrase not found, and build stops.

​
Build and verify

Build the video without an account, then measure the reveals.
  1. Build the video with decktalk build --silent.
  2. Measure two cues with decktalk verify 3:3.1rule 3:3.1p1.
Both rows read changed. The offset column is the time from the cue time to the onset of the reveal, in milliseconds. decktalk verify reports OFF CUE and exits 1 when that time is outside the offset limit. Only a silent build gives the a/v column, because only the click track has clicks. Verify defines every column. If you have an ElevenLabs key in .env, run decktalk build to voice the video. It spends credits on every section, because the last build was silent.

​
The finished section

These are the four files of the section, in one place.

​
Next