Skip to main content

Crate deckhand

Crate deckhand 

Source
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 ratatui Buffer. It receives neutral presenter::KeyPress/presenter::Mouse events.
  • 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) and web (wasm-bindgen + xterm.js; compiled only for wasm32), each a thin translation layer.

§Module map

modulerole
deckdeck model + single-file markdown parsing
configJSON manifest loading
markdownmarkdown → styled ratatui text
highlightlightweight code-block syntax highlighting
themetheming: layout, borders, colors, precedence
qr```qr fences → scannable unicode QR codes
ascii_imagemarkdown images → colored ASCII art
bannerh1_style: banner → block-glyph headings
presentershared presentation core + provider trait
replaysnapshot-replaying terminal provider
paletteconcrete RGB values for exported documents
hintsoverview quick-jump codes
compileflatten any deck to single-file markdown
protopresenter → notes-client wire format
native-onlypresent, term, server, notes, source, snapshot, export, cli, pdf/html (same-named features, on by default)
wasm-onlyweb

§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 go

Modules§

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 as terminal fences).
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 Text renderer with word wrapping.
notes
Presenter-notes follower: connect from any other terminal with deckhand notes and 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.
pdf
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 TerminalProvider for 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.