Expand description
Present markdown slide decks as a TUI.
deckhand turns a plain markdown file (or a JSON manifest) into a full-screen terminal presentation with live embedded terminals, a two-dimensional slide grid, an overview with quick-jump codes, and presenter notes streamed to a second terminal. The same core compiles to WebAssembly and powers an in-browser presenter at https://deckhand.sh.
Most people want the binary:
deckhand talk.md # present
deckhand notes # presenter notes, in another terminal
deckhand compile deck.json # flatten a manifest to one file
deckhand compile talk.md -o talk.pdf # typeset a PDF, one page per slide
deckhand compile talk.md -o talk.html # a self-contained static page§The deck format, in one slide
---
title: my talk
theme:
border_type: rounded
---
# hello ← column 1
---
# demo ← column 2 (`---` = next column)
```terminal rows=10
python3 -q
```
???
presenter notes live after the ??? line
--
## the weeds ← deeper in column 2 (`--` = down)Terminals are real PTYs when presenting natively; on the web they
replay captures baked in by deckhand compile --snapshots.
§Architecture
The crate is split so every presentation context shares one brain:
presenter::Presenter— the platform-independent core: 2-D navigation, layout, theming, the overview, focus/selection, and all drawing into a ratatuiBuffer. It receives neutralpresenter::KeyPress/presenter::Mouseevents.presenter::TerminalProvider— the extension point supplying the live innards of terminal blocks. The native front end provides real PTYs (present::PtyProvider); the wasm front end replays snapshots; your embedding can provide ssh sessions, containers, or recordings.- Front ends:
present(native TUI, crossterm) andweb(wasm-bindgen + xterm.js; compiled only for wasm32), each a thin translation layer.
§Module map
| module | role |
|---|---|
deck | deck model + single-file markdown parsing |
config | JSON manifest loading |
markdown | markdown → styled ratatui text |
highlight | lightweight code-block syntax highlighting |
theme | theming: layout, borders, colors, precedence |
qr | ```qr fences → scannable unicode QR codes |
ascii_image | markdown images → colored ASCII art |
banner | h1_style: banner → block-glyph headings |
presenter | shared presentation core + provider trait |
replay | snapshot-replaying terminal provider |
palette | concrete RGB values for exported documents |
hints | overview quick-jump codes |
compile | flatten any deck to single-file markdown |
proto | presenter → notes-client wire format |
| native-only | present, term, server, notes, source, snapshot, export, cli, pdf/html (same-named features, on by default) |
| wasm-only | web |
§Library quickstart
Parse a deck and walk it with the shared presenter (a tiny provider stands in for terminals):
use deckhand::deck;
use deckhand::presenter::{
Key, KeyPress, Presenter, TermState, TerminalProvider,
};
use ratatui::buffer::Buffer;
use ratatui::layout::Rect;
struct NoTerms;
impl TerminalProvider for NoTerms {
fn prepare(&mut self, _: &deck::TermBlock, _: u16, _: u16) {}
fn state(&self, _: &deck::TermBlock) -> TermState {
TermState::Unavailable
}
fn draw(&mut self, _: &deck::TermBlock, _: Rect, _: &mut Buffer) {}
fn input(&mut self, _: usize, _: &[u8]) {}
fn scroll(&mut self, _: usize, _: isize) {}
fn restart(&mut self, _: &[usize]) {}
fn interactive(&self) -> bool {
false
}
}
let deck = deck::parse("# hello\n---\n# world\n--\n## deeper\n", "demo")?;
let mut presenter = Presenter::new(deck, vec![], NoTerms)?;
presenter.on_key(KeyPress::plain(Key::Char(' '))); // next slide
assert_eq!(presenter.position(), (1, 0));
let area = Rect::new(0, 0, 80, 24);
let mut frame = Buffer::empty(area);
presenter.draw(area, &mut frame); // render anywhere a Buffer can goModules§
- ascii_
image - Images in slides, rendered as colored ASCII art.
- banner
- Banner headings: H1s as large block glyphs.
- cli
- Command-line interface.
- compile
deckhand compile: flatten a deck — typically a JSON manifest with per-slide files — into a single-file markdown deck that presents identically (columns as---, depth as--, notes as???, terminals asterminalfences).- config
- JSON deck manifests: explicit 2-D layout, one markdown file per slide, and slides that are nothing but a terminal.
- deck
- Deck parsing.
- export
- Shared plumbing for
deckhand compile’s output formats. - highlight
- Lightweight syntax highlighting for fenced code blocks.
- hints
- Quick-jump hint codes for the overview (native TUI and web presenter).
- html
deckhand compile -o talk.html: export a deck as a single self-contained static HTML page.- markdown
- Markdown → ratatui
Textrenderer with word wrapping. - notes
- Presenter-notes follower: connect from any other terminal with
deckhand notesand it tracks the presenter live over the unix socket. - palette
- Concrete RGB values for every
ratatui::style::Color, shared by the PDF and HTML exporters. deckhand compile -o talk.pdf: render a deck to a PDF file, one page per slide.- present
- Native TUI front end.
- presenter
- The platform-independent presenter.
- proto
- Wire format between the presenter and the notes client: newline-delimited JSON over a unix socket, presenter → client only.
- qr
- QR codes in slides.
- replay
- A
TerminalProviderfor contexts that can’t run terminals. - server
- Presenter-side notes server: accepts connections on a unix socket and broadcasts the current slide state as JSON lines.
- snapshot
- Bake terminal “screenshots” into a deck at compile time.
- source
- Deck loading from local paths, plain URLs, and GitHub gists.
- term
- Live PTY sessions embedded in slides.
- theme
- Theming: layout, borders, and colors.