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. The website (with a
WebAssembly-powered in-browser demo and gist loader) lives in
site/.
Quick start
# in a second terminal (optional): live presenter 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:
--
---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):
title: my talk
theme:
border_type: rounded
accent: magenta
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):
```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.
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:
```terminal rows=10
python3 -q
```
- The block body is run via
$SHELL -c; leave it empty for an interactive shell. rows=Nsets the viewport height (default 12, max 40);rows=fillexpands 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), theny.sstops a terminal (back to its command preview),Rrestarts it. Pass--eagerto 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-pgdnscroll 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:
```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:

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:
````row
```qr
https://deckhand.sh
```
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/).
-
columnsis 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, orpanes— plus optionaltitle,notes(inline markdown),notes_file, andtheme(per-slide overrides, see Theming). -
A
terminalslide is one big PTY, filling the slide unless you give itrows. -
panesstacks several panes vertically on one slide — any mix of markdown files and terminals, so two or three stacked terminals is just: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```terminalblocks on one slide.) -
Paths are relative to the manifest. Referenced markdown files are one slide each — no
---/--splitting — but???notes and```terminalblocks 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 |
o |
overview grid — each slide shows a short code; type it to jump (or hjkl + enter, or click) |
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, click anywhere else to release, scroll-wheel over a terminal to move through its history, and in the overview click a slide to jump to it. (Mouse events aren't forwarded into the PTY yet, so apps like htop stay keyboard-driven.)
Presenting from a URL or gist
Any deck argument can be a URL:
- 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, thendeck.md, then the only file, then the first.md. A gist containingdeck.jsonplus 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 flattens a JSON deck into a single markdown file that
presents identically — handy for sharing a talk as one artifact:
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 ***
so they don't split slides on re-parse.
Baking in terminal snapshots
If the deck has terminal blocks, compiling requires an explicit choice — because capturing executes the deck's commands on your machine, and skipping silently would lose their output:
# 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.
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 thedeckhand notesview -
a top-level
"theme"object in a JSON deck manifest, or athemeblock in a single-file deck's frontmatter — per-talk styling -
a
"theme"object on an individual manifest slide, or a```themeblock 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:
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:
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/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
- No syntax highlighting in code blocks (yet)
- Slides taller than the window are clipped, not scrolled
- No images
- Unix only (PTYs + unix sockets)