deckhand 0.3.0

Present markdown slide decks as a TUI — live embedded terminals, a 2-D slide grid, presenter notes, and a wasm presenter for the browser
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
# deckhand ⚓

Present slide decks as a TUI. One markdown file in, a full-screen terminal
presentation out — with **live embedded terminals**, a **2-D slide grid**,
a **bird's-eye overview**, and **presenter notes** that follow along in a
separate terminal.

Built in Rust on [ratatui](https://ratatui.rs). The website (with a
WebAssembly-powered in-browser demo and gist loader) lives in
[`site/`](https://github.com/akesling/deckhand/tree/main/site).

## Install

```sh
curl -fsSL https://deckhand.sh/install.sh | sh   # prebuilt binary (macOS/Linux)
cargo install deckhand                           # or build from source
```

Binaries for macOS (arm64/x86_64) and Linux (x86_64/arm64) are also on
[GitHub releases](https://github.com/akesling/deckhand/releases).

## Quick start

```sh
deckhand https://deckhand.sh/decks/demo.md   # or any local .md file

# in a second terminal (optional): live presenter notes
deckhand notes
```

## Deck format

Decks come in two flavors: a **single markdown file** with separators, or a
**JSON manifest** that lays out one markdown file per slide (see below).

A single-file deck uses two separators for its two dimensions:

```markdown
# first topic          ← column 1, top

---

# second topic         ← column 2, top

--

## the weeds           ← column 2, one level deeper
```

- `---` on its own line starts a new **column** (earlier / later)
- `--` on its own line starts a **deeper** slide in the same column
  (shallower / deeper — detail you only show if asked)

Both are ignored inside fenced code blocks.

Single-file decks can open with **frontmatter** carrying a title and a
theme (same schema as JSON manifests, see Theming):

```markdown
---
title: my talk
theme:
  border_type: rounded
  accent: magenta
---

# first slide
```

The leading block is only treated as frontmatter when it parses as a
YAML mapping — a bare `---` at the top of a deck still just separates
columns like it always did.

Individual slides take theme overrides via a `theme` fence anywhere on
the slide (works in single-file decks and in per-slide files referenced
from a manifest):

````markdown
# demo time

```theme
margin: 0
accent: red
```

```terminal rows=fill
htop
```
````

### Presenter notes

Everything after a bare `???` line is presenter notes for that slide:
invisible when presenting, streamed to `deckhand notes`.

```markdown
# pricing

it's complicated

???

Don't improvise here. Point at the table and move on.
```

### Embedded terminals

A fenced code block whose info string is `terminal` becomes a live,
interactive PTY on the slide:

````markdown
```terminal rows=10
python3 -q
```
````

- The block body is run via `$SHELL -c`; leave it **empty** for an
  interactive shell.
- `rows=N` sets the viewport height (default 12, max 40); `rows=fill`
  expands it to all remaining slide height.
- **Nothing executes without consent**: by default each terminal shows
  the command it *would* run, and you approve it in-deck — press `t`
  (or click), then `y`. `s` stops a terminal (back to its command
  preview), `R` restarts it. Pass `--eager` to start every terminal
  automatically when its slide first appears.
- Once running, terminals keep running while you navigate elsewhere,
  and die when deckhand exits.
- Each terminal keeps 10,000 lines of history: while focused,
  `shift-pgup`/`shift-pgdn` scroll it (half a page at a time), `shift-↑`/
  `shift-↓` go line by line, and typing anything snaps back to live.
- Once a terminal has history, a scrollbar appears on its right border —
  thumb sized to viewport-vs-history, accent-colored while focused.

### Syntax highlighting

Fenced code blocks with a language tag get lightweight highlighting —
keywords, strings, comments, numbers/constants, called functions, and
Capitalized types — for rust, python, javascript/typescript, go,
c/c++, sh, json, yaml, toml, and sql; unknown languages render plain.
It's a small built-in tokenizer (no grammar engine), so it works
identically in the browser presenter and keeps the wasm bundle small.
Colors are the theme's `code_keyword`, `code_string`, `code_comment`,
`code_literal`, `code_function`, and `code_type`, defaulting to a One
Dark-flavored truecolor palette (RGB, so terminal palettes can't
remap it).

### QR codes

A fenced block whose info string is `qr` renders its body — a URL, some
text — as a scannable QR code, drawn black-on-white regardless of the
terminal palette so phone cameras actually read it:

````markdown
```qr
https://deckhand.sh
```
````

Great for the "slides are at…" closer. Works in the browser presenter
too.

### Images as ASCII art

A markdown image alone on its own line renders as colored ASCII art,
scaled to the slide and resolved against the deck's directory:

```markdown
![the architecture](diagrams/arch.png)
```

PNG, JPEG, GIF, and WebP. Images referenced mid-sentence stay inline
text (`[image: alt]`), and the browser presenter shows a placeholder —
pixels need a filesystem.

### Side-by-side layout

A fenced block whose info string is `row` lays its cells out
side-by-side, splitting the slide width equally; `||` on its own line
separates cells. A cell stacks anything a slide can hold — markdown,
code blocks, terminals, QR codes, images — except another row. Make
the outer fence longer than any fence inside the cells:

`````markdown
````row
```qr
https://deckhand.sh
```
||
```terminal rows=10
python3 -q
```
````
`````

Cells are top-aligned and the row is as tall as its tallest cell.
`rows=fill` terminals inside a row fall back to their fixed height
(default 12) — "the rest of the slide" isn't a height a side-by-side
cell can claim.

## JSON decks

For bigger talks, point deckhand at a manifest instead:
`deckhand deck.json` (see `examples/json-demo/`).

```json
{
  "title": "my talk",
  "columns": [
    "slides/intro.md",
    ["slides/topic.md", "slides/topic-deep.md"],
    { "terminal": { "command": "htop" }, "title": "live demo" },
    { "file": "slides/fin.md", "notes_file": "slides/fin-notes.md" }
  ]
}
```

- `columns` is the presentation left-to-right; each entry is a **string**
  (single-slide column), an **array** (a column with depth, top first), or
  an **object**.
- Object slides take exactly one of `file` (markdown), `terminal`, or
  `panes` — plus optional `title`, `notes` (inline markdown),
  `notes_file`, and `theme` (per-slide overrides, see Theming).
- A `terminal` slide is one big PTY, filling the slide unless you give it
  `rows`.
- `panes` stacks several panes vertically on one slide — any mix of
  markdown files and terminals, so two or three stacked terminals is just:

  ```json
  { "panes": [
      "slides/context.md",
      { "terminal": { "command": "python3 -q", "rows": 8 } },
      { "terminal": {} }
  ] }
  ```

  Markdown panes contribute their `???` notes (concatenated) and the first
  one names the slide; fill-height terminals split the leftover space
  evenly. (In single-file markdown decks the same thing works by putting
  multiple ` ```terminal ` blocks on one slide.)
- Paths are relative to the manifest. Referenced markdown files are one
  slide each — no `---`/`--` splitting — but `???` notes and
  ` ```terminal ` blocks inside them still work.

## Live reload

Local decks **live-reload while presenting**: deckhand watches the deck
file — and for manifests, every referenced slide and notes file, plus
your user theme — and hot-swaps the deck when anything changes. Your
position is kept (clamped if the deck shrank), live terminals survive
when the deck's terminal blocks are unchanged, and a mid-edit parse
error keeps the current deck with the error on the status bar. Disable
with `--no-watch`. Remote decks aren't watched.

## Keys

| key | action |
|-----|--------|
| `←`/`h`, `→`/`l` | previous / next column |
| `↓`/`j`, `↑`/`k` | deeper / shallower |
| `space`, `n` | next slide (walks every column depth-first) |
| `shift-space`, `backspace`, `p` | previous slide |
| `g`, `G` | first / last column |
| `pgdn`, `pgup` | scroll a slide taller than the window, then advance |
| `o` | overview grid — each slide shows a short code; type it to jump (or `hjkl` + `enter`, or click) |
| `/` | search slides — type to filter (titles, body, notes, commands), `↓`/`↑` select, `enter` jumps, `esc` closes |
| `1`-`9` | select a terminal pane (marked with `▸`) |
| `t`, `enter` | run (after a `y` confirmation) / focus the selected terminal |
| `Ctrl-q` | release terminal focus |
| `shift-pgup`/`shift-pgdn` | scroll terminal history (also `shift-↑`/`shift-↓`) |
| `s` / `R` | stop / restart the selected terminal |
| `?` | help |
| `q` | quit |

While a terminal is focused, every key except `Ctrl-q` and the
`shift-`scroll keys goes to the PTY.

With several terminals on one slide, each shows its number in the title
and `▸` marks the one `t` will focus; the others' hint shows which number
selects them.

The mouse works too: **click** a terminal to select and focus it (apps
that asked for the mouse get the click), click anywhere else to
release, and in the overview click a slide to jump to it. The
**scroll-wheel** over a terminal reaches whatever wants it: mouse-aware
apps (htop) get real wheel events, full-screen apps without mouse
reporting (less, vim) get arrow keys, and plain shells scroll
deckhand's own history view. Off-terminal, the wheel scrolls a slide
taller than the window (`▲`/`▼` in the corners mark clipped content).

## Presenting from a URL or gist

Any deck argument can be a URL:

```sh
deckhand https://example.com/talks/deck.md
deckhand https://gist.github.com/alex/abc123
deckhand compile https://gist.github.com/alex/abc123 -o talk.md
```

- A plain URL fetches that file. JSON manifests work remotely too —
  their relative paths (slides, `notes_file`) fetch against the
  manifest's URL.
- A **gist page URL** is resolved through the GitHub API: deckhand looks
  at the gist's files and picks the deck by priority — `deck.json`, then
  `deck.md`, then the only file, then the first `.md`. A gist containing
  `deck.json` plus slide files works as a full multi-file deck (manifest
  paths resolve against the gist's filenames).
- Embedded terminals in remote decks run in your current directory.

### Compiling a manifest to one file

`deckhand compile` turns a deck into a single artifact. The default
format flattens a JSON deck into one markdown file that presents
identically — handy for sharing a talk (the output format follows
`-o`'s extension; see [Exporting](#exporting-pdf-and-html) for
`.pdf`/`.html`):

```sh
deckhand compile deck.json -o talk.md
deckhand talk.md
```

The deck's title and deck-level theme are preserved as frontmatter, and
per-slide themes as ` ```theme ` blocks. Caveats: per-slide `title`
overrides have no single-file syntax and fall back to what the content
implies; bare `---`/`--` lines inside slide bodies are rewritten to `***`
(and bare `||` lines inside row cells escaped) so they don't split
slides on re-parse.

### Baking in terminal snapshots

If the deck has terminal blocks without baked snapshots, compiling
requires an explicit choice — because capturing *executes the deck's
commands* on your machine, and skipping silently would lose their
output (a deck whose terminals are all already snapshotted needs no
flag):

```sh
deckhand compile deck.json -o talk.md --snapshots      # run + capture
deckhand compile deck.json -o talk.md --no-snapshots   # placeholders
# capture knobs: --snapshot-wait-ms 3000 --snapshot-cols 100
#                --snapshot-root ~/demo
```

With `--snapshots`, each block runs in a real PTY, output settles, and
the screen is captured into the compiled file. `--snapshot-root` sets
the working directory captures run in — handy for controlling what your
shell prompt shows — and defaults to the deck's directory, matching
live presenting. Decks without terminal blocks need no flag.

The capture is stored inside the terminal fence as a `%%snapshot
COLSxROWS` marker plus base64-encoded ANSI — so contexts that can't
spawn PTYs (the web presenter) replay the real, colored output instead
of showing a placeholder. Native presenting always runs the command
live and ignores snapshots.

## Exporting: PDF and HTML

`deckhand compile` also renders a deck through the same layout engine
that presents it — theming, banner headings, QR codes, and ASCII-art
images included — to a **PDF** (one page per slide) or a **single
self-contained static HTML page**. The `-o` extension picks the
format (or force one with `--to md|pdf|html`):

```sh
deckhand compile talk.md -o talk.pdf
deckhand compile talk.md -o talk.html
deckhand compile deck.json -o slides.pdf --cols 100 --rows 30 --font-size 12
```

Both formats:

- Slides are a terminal-cell grid (`--cols` × `--rows`, default
  100 × 30).
- Colors resolve like the web presenter: xterm defaults on a dark page.
- Terminal blocks render their baked snapshots (see
  [snapshots]#baking-in-terminal-snapshots). A deck with
  unsnapshotted terminals requires `--snapshots` (runs the commands
  and captures their output) or `--no-snapshots` (placeholders).
- Each is a cargo feature (`pdf`, `html`), on by default; build with
  `--no-default-features` for a deckhand without them.

**PDF**: real, selectable text in an embedded, subsetted DejaVu Sans
Mono — box-drawing borders, block glyphs, and QR modules are drawn as
vector paths, so borders connect seamlessly and QR codes stay
scannable at any zoom. `--font-size` (points) scales the page around
the grid. Slide titles become PDF bookmarks: one entry per column,
deeper slides nested beneath it.

**HTML**: one file, no external assets, no wasm — each slide is a
`<pre>` of styled text. Arrow keys / hjkl / space walk the same 2-D
grid as presenting (the URL hash tracks `#col.row`), `f` goes
fullscreen, text scales to fit the window, and printing lays slides
out one per page.

## Theming

Layout, borders, and colors are configurable. Three sources, merged field
by field (each later one wins):

- `~/.config/deckhand/theme.json` (or `$XDG_CONFIG_HOME/deckhand/theme.json`)
  — your personal defaults, applies to every deck including markdown ones
  and the `deckhand notes` view
- a top-level `"theme"` object in a JSON deck manifest, or a `theme` block
  in a single-file deck's frontmatter — per-talk styling
- a `"theme"` object on an individual manifest slide, or a ` ```theme `
  block in a slide's markdown — per-slide overrides, scoped to that
  slide's content (margins, width, alignment, borders, markdown colors);
  the status bar and overview keep the deck theme. When both exist for
  one slide, the manifest's wins field by field. e.g. a full-bleed
  terminal slide:

  ```json
  { "terminal": { "command": "htop" },
    "theme": { "margin": 0, "max_width": 500 } }
  ```

```json
{
  "max_width": 84,
  "max_height": 30,
  "margin": 2,
  "margin_y": 1,
  "align_x": "center",
  "align_y": "top",
  "pin_title": true,
  "title_gap": 1,
  "border_type": "rounded",
  "accent": "magenta",
  "muted": 244,
  "term_border": "gray",
  "snapshot_border": "yellow",
  "status_bg": "#3a3a3a",
  "status_fg": 250,
  "h1_style": "banner",
  "h1": "yellow",
  "h2": "light-yellow",
  "bullet": "magenta",
  "quote": "green",
  "link": "light-blue",
  "inline_code": "yellow",
  "code_bg": 235,
  "code_fg": 252,
  "code_keyword": "#c678dd",
  "code_string": "#98c379",
  "code_comment": "#7f8490",
  "code_literal": "#d19a66",
  "code_function": "#61afef",
  "code_type": "#e5c07b",
  "qr_dark": "#102040",
  "qr_light": "#fdf6e3"
}
```

Every field is optional. Colors take a name (`"cyan"`, `"light-blue"`),
hex (`"#rrggbb"`), or a 0-255 palette index. `snapshot_border` styles
terminals that are showing a baked-in snapshot, superseding
`term_border` for those (unset = same as `term_border`). `border_type`
is `plain`, `rounded`, `double`, or `thick`.

**Layout** is one content box, two axes, the same three questions per
axis — and three rules: margins always win, caps bound everything
drawn, alignment only places what's left.

| axis | air (min) | cap (max) | leftover space |
|------|-----------|-----------|----------------|
| x | `margin_x` (default 2) | `max_width` (default 96) | `align_x`: left / **center** / right |
| y | `margin_y` (default 0) | `max_height` (default unlimited) | `align_y`: top / **center** / bottom |

`margin` sets both axes at once; the per-axis keys win over it. Units
are terminal cells (columns / rows). `max_height` caps everything the
slide draws — fill terminals and a pinned title included.

`pin_title` anchors a slide-leading heading to the top of the content
area (i.e. at row `margin_y`), with `title_gap` blank rows (default 1)
below it; the body lays out in the remaining space, still following
`align_y`. That's how a title sits on the same row on every slide
while the body stays centered.

`h1_style: "banner"` draws level-1 headings as large block glyphs,
three rows tall (A–Z, 0–9, light punctuation — case-insensitive). A
heading the font can't render, or that won't fit the width, falls
back to a normal H1. The demo decks use it on their title slides.

`qr_dark`/`qr_light` color QR blocks (modules / background, quiet zone
included) and default to true black on true white. Restyle at your own
risk: scanners need a dark code on a light background with strong
contrast — dark navy on cream scans fine, an inverted or low-contrast
pairing often won't.

Tip: prefer palette indexes (16-255) or hex over ANSI names for grays.
Schemes like solarized remap the 16 ANSI colors — ANSI "dark gray" becomes
nearly invisible against a solarized background, which is why deckhand's
own defaults use indexed grays.

## Presenter notes over a socket

`deckhand present` listens on a unix socket (default
`$TMPDIR/deckhand.sock`) and broadcasts the current slide, its notes, the
next slide's title, and a talk timer. `deckhand notes` renders that from
any other terminal — a second window, a tmux pane, or over ssh to the same
machine. Reconnects automatically.

Running two decks at once? Give each a socket:

```sh
deckhand present talk.md --socket /tmp/talk.sock
deckhand notes --socket /tmp/talk.sock
```

## Development

Repo tooling lives in `scripts/` (each self-contained and executable):

| script | does |
|--------|------|
| `scripts/lint.sh` | all linters: `cargo fmt --check`, clippy (native + wasm32), shellcheck, biome |
| `scripts/check.sh` | lint + `cargo test` + TypeScript type-check |
| `scripts/coverage.sh` | line-coverage report via cargo-llvm-cov (HTML + summary; CI uploads lcov) |
| `scripts/build-wasm.sh` | wasm module → `site/wasm/` (`--dev` for fast builds) |
| `scripts/build-site.sh` | full site build → `site/_site/` |
| `scripts/dev.sh` | dev server: 11ty live reload + `bun --watch` + wasm rebuild on Rust changes |
| `scripts/publish.sh` | crates.io publish from a pristine clone; dry-run by default (`--i-know-what-i-am-doing` to publish) |
| `scripts/deploy-site.sh` | deploy `site/_site/` to Cloudflare Pages (production + a permanent per-release alias) |
| `scripts/release.sh` | cut a release: checks + site build + dry-run, then tag `v<version>`, push (CI deploys the site), and publish to crates.io; dry-run by default |

CI (`.github/workflows/ci.yml`) runs the same gates on PRs and merges to
main, plus the PTY tests and an MSRV check; everything is pinned —
actions by commit SHA, the toolchain by `rust-toolchain.toml`, deps by
`Cargo.lock`/`bun.lock` (cargo runs `--locked`, bun `--frozen-lockfile`).
Dependabot PRs don't run CI automatically; trigger the workflow manually
after review.

## Current limitations

- Images render as ASCII art, and only when presenting natively — the
  browser presenter shows a placeholder
- Unix only (PTYs + unix sockets)