14. Presenting: keys, touch, overview, print

14. Presenting: keys, touch, overview, print

• Break timer (t): opens a full-screen HUD that floats over the deck. Number keys pick a preset and start the countdown; Space pauses and resumes; t or Esc closes it. At zero the digits turn critical and flash. While it is open the deck does not advance, so it is safe to leave projected during a break. It needs no network and works from file://. The presets default to 5,10,15,20,30,45,60 minutes; override them in si.conf with timer.time and timer.unit (minutes or seconds). The countdown shows as digits or, with timer.face: analog, an analog sport-clock dial — toggle it live in the HUD. A timer.animation runs a themed animation layer behind the translucent HUD (SLIDE │ ANIMATION │ TIMER) — built-ins waves, orbit, bokeh, or your own; list several (comma-separated) for a toggle (a None option is always offered). Once the countdown starts the HUD hides its presets and toggles so only the clock and the animation show — Space still pauses; any other key or a click brings the controls back. See §16 and docs/timer-animations.md.

• Find a slide (/): opens a search palette over the deck. Type to search slide titles and body text — results list the slide number, title and the matched snippet, ranked title-matches first; ↑/↓ move the selection and Enter (or a click) jumps. Type a number to go straight to that slide (e.g. /12 → slide 12). Esc closes. Disable with feature.find: off. Below the slides it also lists the other pages of the folder, matched loosely (the letters in order, not necessarily together: idx or inde finds index.html, lab3 finds lab-03-quorum.html): the index, the other decks and labs, their PDFs (--pdf), any other .html already in the output folder, and the links.* of si.conf. Enter opens the page. si build writes the list into each deck (names and titles only, so it works from file://); si play reads the folder on every request.

• Draw (a): a transient pen over the current slide, for circling or underlining as you talk. Drag to draw (mouse, touch, or pen — pen pressure varies the stroke); the toolbar picks the colour (accent, red, green, ink) and the brush size (thin / medium / thick); c cycles colour, e erases strokes, z undoes the last, x clears all, Esc turns it off. Strokes use the theme colours and clear when you change slides; they are not saved and do not print.

• The URL hash is the position (#7, #7.2); reloads keep it, so live reload in si play stays on your slide.

• A progress bar and a slide counter (with the step) sit at the bottom; the controls appear when the mouse moves.

• When a slide is too tall for the window its canvases, diagrams and images shrink first (down to about 60 %) so a figure plus bullets clears the footer, then the fluid type shrinks a little, then the slide scrolls; nothing is cut off. The figure cap itself is the --si-figure-max token (default 60cqb; the center layout adds 6cqb, columns 14cqb), so a theme with a taller footer band can lower it for every slide:

  CSSCopy

  :root { --si-figure-max: 52cqb; }

• Print (browser print, or print to PDF): one slide per page at the deck aspect, every step revealed, canvases in their final state. si build --pdf writes a <name>.pdf next to each deck using headless Chrome (needs Chrome or Chromium installed; without it, HTML is still written).

• Video: si build talk.md --mp4 films the deck to <name>.mp4 (1920×1080, H.264): every slide and every build step as the audience sees it, each held for its share of the slide's (N min) (else 3 s), dissolving into the next in 0.4 s. --dwell 2 holds every view 2 s instead, for a short teaser:

  ShellCopy

  si build talk.md --mp4 --dwell 2   # talk.mp4: a 2 s look at every slide and step

  It needs headless Chrome and ffmpeg (brew install ffmpeg). The canvas morph and the slide transition become a dissolve between two still views.

• Open on a phone: run si play <dir> --addr 0.0.0.0:7070 to serve on your network; si play then prints a LAN URL and a QR code to scan. (The default address is loopback-only, so it prints the --addr hint instead.)

• Play terminal (`, backtick): a drawer of real shells on your machine for live demos — play-only and loopback-only, never shipped in a built deck. Full reference: docs/terminal.md.

• Runbook (front matter runbook: cockroach.json): a command cheat-sheet in a right drawer of the play terminal. The JSON is a list of categories, each with entries (label, description, command, target: sql|bash):

  JSONCopy

  { "categories": [ { "name": "Cluster Info", "entries": [
      { "label": "Show Nodes", "description": "live nodes",
        "command": "SELECT node_id, is_live FROM crdb_internal.gossip_nodes;", "target": "sql" } ] } ] }

  Each command is syntax-highlighted (by target) so you can read it at a glance; there's a filter box. Every entry has Copy (puts the command at the shell prompt without running it, and on the clipboard) and Run (the same, then Enter); clicking the entry itself is Copy, Shift-click Run. A command waits until the shell has drawn its prompt, and is sent as a paste where the shell supports it (zsh, bash 5.1+), so a multi-line command shows whole and runs only on Enter. The shape matches the cockroach-engineering-tool VS Code extension's runbook.json, so an exported runbook drops in unchanged. Like the terminal, it appears only in si play on a loopback address — a built deck never loads it, so rules #2/#7 still hold for shipped HTML. si check validates the path and JSON.

  A command may hold placeholders: {{name}} or {{name:default}} (name [A-Za-z_][A-Za-z0-9_-]*, default any text without }). The drawer asks for a value for each distinct name (first occurrence and its default win), then Copy or Run the command with every occurrence replaced; Esc cancels and types nothing. Placeholders are highlighted in the command.

• Demos (front matter demos: ../demos/): demo scripts, plain markdown, in a second side panel of the play terminal (▶ Demos, one panel open at a time). A drop-down lists the demos by their # title (else the file name); the panel shows the whole script (headings, prose, tables, > quotes) and every ```bash / sh / shell / zsh / console / sql / powershell block gets Copy and Run, as in the runbook. Blocks in any other language (```text for expected output) stay plain. The value is a comma-separated list of .md files or folders, relative to the deck; a folder gives its *.md except README.md, index.md and _-prefixed files. Like the runbook: play and loopback only, never in a built deck; si check reports a missing path. The last demo picked is remembered.

  markdownCopy

  ---
  title: Session 1
  demos: ../demos/
  ---

  JSONCopy

  { "label": "Pods", "command": "kubectl -n {{ns:messaging}} get pods {{pod}}", "target": "bash" }

  Not placeholders, typed verbatim: {{.Server.Version}}, {{json .}}, ${HOME}, {print $1}, {a: .b}, and the Go-template keywords {{end}}, {{else}}, {{break}}, {{continue}}, {{nil}}, {{true}}, {{false}}. The file may also carry a top-level name (the drawer title) and description.

Studio (si --web)#

si --web [dir] [--addr 127.0.0.1:7070] [--no-open] opens a browser editor for the decks in dir: file tree, markdown editor, live preview and the si check report. It listens on a loopback address only and is never part of a built deck. See docs/studio.md.

si --web examples --no-open

In the terminal#

si play talk.md --terminal presents the deck in the terminal itself: no browser, over SSH, in tmux. Every rule above draws as text and colour from the same markdown:

• The theme's colours (its dark values, or light with mode: light): accent, muted text, the ==highlight== band, card colours.
• Titles of title, section and closing slides in block letters made of half-block characters (falling back to bold text where a letter has no glyph or a word does not fit); the big number of a big-number slide too.
• Builds (<!-- step -->, <!-- steps -->) reveal one at a time; going back to a slide shows it whole.
• Layouts: columns (<!-- column -->, two-col and split with text left and media right) side by side when the terminal is 60 columns or wider, stacked below that; center, quote and big-number centred.
• Code highlighted with si's own highlighter, in a box with its title, hl= lines, linenos and callouts (❶); tables with borders and the column alignment; cards, badges and logo lockups as text.
• Images (PNG, JPEG, GIF) as real pictures in terminals that can show them (Kitty, Ghostty and WezTerm through the Kitty graphics protocol; iTerm2 through its inline images), and as half-block pixels everywhere else, inside tmux too (SI_PICTURES=kitty|iterm|halfblock overrides the guess); stage diagrams as boxes and arrows, the travelling dot moving along them.
• Animated canvases (<!-- svg: -->) drawn with characters: boxes, wires, text and dots from the SVG's shapes, in the state the deck has reached (the same words, +w / -w and build-step ops as in the browser). The helper attributes work (data-show, data-hide, data-ok, data-alert, data-flow, data-packets, data-grow) and so do the canvas's own CSS state rules for opacity, display, fill and transform (translate, scaleX). They move: packets travel along their wires, flows march, alerts pulse, and a part that moves between two states slides there when you press →. Other CSS (offset-path, counters, filters) shows the end state. SVG images, Mermaid diagrams and video show a labelled placeholder: the browser draws them.

Keys are the browser's: → Space n next, ← p back, g / G first and last, o overview, t restart the timer, ? keys, q quit. The deck reloads when a file changes, and the slides reflow when the terminal is resized.

si play talk.md --terminal --notes in a second terminal (another tmux pane, or the laptop screen while the projector shows the first) is the teleprompter: it follows the presenter over a local socket and drives it back (Space and ← move the slides from the notes). It shows the Notes: script with the [CLICK] cues as badges (done ones ticked, the next one highlighted), slide and total timers against the (N min) plan with the pace (on time, ahead, behind), the clock, and the current and next slide. It scrolls by itself (a on / off, + / - speed, ↑ ↓ by hand); Tab switches to the Points:. It also follows a deck open in a browser: with si play (or si serve) running, --notes listens to the server at --addr (default 127.0.0.1:7070) for the page of the same name, and Space / ← move the browser deck. Without either it moves on its own.

si play talk.md --terminal --dump 4 --size 100x30 prints slide 4 with every build shown (ANSI colours) and exits: for scripts, READMEs and checks.