A deck is a folder of Markdown files. toboggan builds it, serves it over
WebSocket + REST, and every connected client stays on the same slide and the
same reveal — a browser on the projector, a terminal on your laptop, a phone in
your hand.
toboggan -p my-talk # build in memory, serve, reload on saveThat one command covers the whole authoring loop. There are also exporters (a self-contained HTML deck, a PDF, a thumbnail overview), a presentation linter, a presenter view with notes and a timer, and an MCP server for writing slides with an LLM.
Mermaid diagrams and LaTeX math are drawn while the deck builds, not in the
browser, so a mermaid fence and a $…$ expression look the same on the
projector, in the exported HTML and in the PDF — and a broken one fails the
build rather than the talk.
Note: this is an educational and fun project, built to explore how far Rust reaches — the same domain crate drives an axum server, a WebAssembly browser client, a ratatui terminal, an iced desktop window, and an iOS app over UniFFI. It works, and it has given real talks, but it is a playground first.
Releases publish x86_64-unknown-linux-gnu and aarch64-apple-darwin binaries:
# Linux x86_64 / macOS Apple Silicon — pick your target
target=aarch64-apple-darwin
curl -fsSL "https://github.com/ilaborie/toboggan/releases/latest/download/toboggan-$target.tar.gz" \
| tar -xz -C ~/.local/bin
toboggan --versionWarning
Do not run cargo install toboggan. The name toboggan on crates.io
belongs to an unrelated project; you will get a stranger's binary that happens
to share the name, and every command below will fail on unrecognised
arguments. This project is not published to crates.io.
Building from source needs the web toolchain too: toboggan-server embeds
toboggan-web/dist at compile time, and its build.rs fails when that folder is
absent.
git clone https://github.com/ilaborie/toboggan
cd toboggan
mise build:web # wasm-pack + pnpm → toboggan-web/dist
cargo install --path toboggan# Scaffold a deck: slides/, public/, toboggan.toml, a jj repo, MCP + skill wiring
toboggan new -p my-talk --title "My Presentation"
# Build it in memory and serve it, reloading whenever a file changes.
# -p defaults to ".", so `cd my-talk && toboggan` also works.
toboggan -p my-talkThen open:
| Route | What it is |
|---|---|
/ |
Homepage — links to everything below, and the QR code the phone app scans |
/run |
The deck. This is what goes on the projector |
/presenter |
Notes, the next slide, a timer and pacing |
/slides |
Thumbnail overview with search |
/guide |
The full authoring guide, served with any deck |
/download.pdf |
The deck as a PDF (needs typst) |
/doc |
OpenAPI reference for the REST API |
The guide's source lives in examples/toboggan-guide/
— a real Toboggan deck you can read on disk, or lint and build like any other.
| Command | Purpose |
|---|---|
toboggan -p <folder> |
Build + serve with a folder watch (the default action) |
toboggan watch -p <folder> |
The default action, named explicitly |
toboggan build -p <folder> -o out.{toml,json,yaml,html,typ} |
Build to a file |
toboggan serve -p <talk.toml> |
Serve an already-built talk (a file, not a folder) |
toboggan new -p <dir> |
Scaffold a presentation |
toboggan lint -p <folder> |
Lint the deck (--format, --deny, --no-spell) |
toboggan stats -p <folder> |
Word counts and duration estimates |
toboggan pdf -p <folder> |
Render a PDF (needs typst) |
toboggan thumbnails -p <folder> |
Per-slide PNGs (photographed in a headless browser) + overview.html + search |
toboggan tui / toboggan desktop |
Clients against a running server |
toboggan openapi |
Emit the bundled OpenAPI document |
toboggan mcp [serve|init] |
MCP authoring server, or install it for Claude Code |
toboggan skills |
Install the authoring skill for Claude Code |
toboggan ci |
Generate the GitHub Pages workflow that publishes the deck |
toboggan completion <shell> |
Print a completion script (bash/zsh/fish/…) |
toboggan build -p ./my-talk/slides -o talk.html # a single navigable file
toboggan lint -p ./my-talk/slides --format github
toboggan pdf -p ./my-talk/slidestoboggan new writes a toboggan.toml listing every setting, commented out with
its default — it is the reference for what can be configured. Anything you can
pass as a flag can live there instead:
default-command = "lint" # what a bare `toboggan` does
[build]
theme = "Solarized (dark)"
wpm = 130
mermaid-config = "mermaid.json" # defaults for mermaid diagrams
[serve]
open-presenter = trueFiles are read from the deck directory, then each parent directory, then
~/.config/toboggan/config.toml — so a repo of several decks can share a house
style and one deck can override it. Precedence, strongest first:
CLI flag > TOBOGGAN_* env var > nearest toboggan.toml > … > user global > default
An unknown key is an error rather than a silent no-op, so a typo tells you.
The server binds to 127.0.0.1 by default, and a client connecting from the
machine running the server may drive the deck. Open it to the room with
--host 0.0.0.0 and the rule changes:
/, /run, /api/talk |
navigation | /api/terminal |
|
|---|---|---|---|
| from this machine | ✅ | ✅ | ✅ |
| from the network | ✅ | ✗ | ✗ |
from the network, with --presenter-token |
✅ | ✅ | ✅ |
The embedded terminals spawn a real shell on the presenter's machine, so the
room gets to watch and nothing more. A second device joins as a presenter by
carrying the token: http://<your-ip>:8080/run?token=….
See SECURITY.md for the full posture.
/presenter is the same application as /run with the things a presenter needs
around it — the next slide, the notes for where you are, and a status strip with
the clock, an elapsed timer, deck progress, and how far ahead or behind the
deck's declared duration you are running. The current slide is the real deck
laid out at projector width and painted small, so a line that wraps here wraps
in the room; the next one is the still the slide overview took of it.
g, / or Ctrl/Cmd+K opens the slide picker: every slide as a
thumbnail, over a search box that reads each slide's title, the part it is in,
its body and its speaker notes — mid-talk you usually remember what you meant
to say about a slide rather than what it shows. Diagram labels and figure
captions are searched too. Arrows move, Enter jumps, Esc closes. The
pictures are photographed as the server starts, so they are there when you first
look; --no-eager-thumbnails puts that back to the first request.
--open-presenter opens both windows at once: this one on your screen, the deck
on the projector.
Every client speaks the same WebSocket protocol and stays in sync with the rest.
Web /run |
Web /presenter |
TUI | Desktop | iOS | Android | |
|---|---|---|---|---|---|---|
| Slides | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Step reveals | ✅ | ✅ | ✅ | — | ✅ | ✅ |
| Speaker notes | — | ✅ | ✅ | ✅ | ✅ | — |
| Next-slide preview | — | ✅ | ✅ | ✅ | ✅ | — |
| Elapsed timer and pacing | — | ✅ | — | ✅ | ✅ | — |
| Embedded terminals | ✅ | — | — | — | — | — |
| Presenter remote (PageUp/PageDown) | ✅ | ✅ | ✅ | ✅ | n/a | n/a |
| Go to slide by number | ✅ | ✅ | ✅ | — | ✅ | — |
| Shows the role it was granted | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Fullscreen | ✅ f |
— | n/a | ✅ F11 |
— | — |
| Blank the screen | ✅ . w |
— | — | — | — | — |
| Help overlay | ✅ F1 |
— | ✅ h |
✅ h |
— | — |
The desktop client renders a slide's Markdown natively rather than mirroring the
deck, and the source it is given has every reveal already in it — so it shows the
whole slide whatever step the room is on. That is deliberate: it is a reading
surface for the speaker, not a second projector. /presenter is the view that
shows the room's own rendering, frame for frame.
- Web (
toboggan-web) — TypeScript + WebAssembly, embedded in the binary./runis the deck;/presenteris the same application with notes, the next slide and a timer around it. Open both with--open-presenter. - Terminal (
toboggan tui) — ratatui; renders slides as text, with notes, a next-slide preview and a slide list. Good over ssh. - Desktop (
toboggan desktop) — a native iced window. - iOS (
TobogganApp/) — SwiftUI over thetoboggan-mobilecrate via uniffi. The same crate backs Android throughtoboggan-android.
toboggan ci writes the whole workflow for you:
toboggan ci # -> .github/workflows/pages.yml, at the repo root
toboggan ci --stdout # print it instead
toboggan new -p my-talk --ci # scaffold a deck with it already in placeIt pins the action to the release matching your toboggan binary and works out
the deck's path relative to the repository root, so a deck in a subdirectory gets
a workflow that points at it. Then enab
8000
le Settings → Pages → Source: GitHub
Actions. The file is yours to edit afterwards; re-running leaves it alone
unless you pass --force.
Underneath is a composite action you can also use directly:
- uses: ilaborie/toboggan@v0.3.0
with:
folder: ./slides # default ./slides
outputs: html,pdf,thumbnails
out-dir: dist # default dist
lint: true # lint first; errors annotate the PR diff
lint-deny: error # info | warning | error
base-url: "" # only for absolute asset URLs
version: v0.3.0 # release of toboggan to installThe generated file is the same one committed at
examples/github-pages/pages.yml — a test
keeps that copy identical to what the command emits. This repo uses the action
on itself; see .github/workflows/pages.yml,
which publishes the guide deck.
flowchart LR
MD["slides/*.md"] --> CLI[toboggan-cli<br/>parser + renderers]
CLI --> CORE[toboggan-core<br/>Talk · Slide · Content]
CORE --> SRV[toboggan-server<br/>axum · WS + REST]
CLI -.-> OUT["html · typst · pdf<br/>thumbnails"]
CORE --> LINT[toboggan-lint]
CORE --> STATS[toboggan-stats]
CORE --> MCP[toboggan-mcp]
SRV <-->|WebSocket| WEB["toboggan-web<br/>(wasm)"]
SRV <-->|WebSocket| CLIENT[toboggan-client]
CLIENT --> TUI[toboggan-tui]
CLIENT --> DESK[toboggan-desktop]
CLIENT --> MOB["toboggan-mobile<br/>(uniffi)"]
MOB --> IOS[TobogganApp<br/>SwiftUI]
MOB --> AND[toboggan-android]
toboggan-core holds the domain model and the wire protocol, and depends on
nothing else in the workspace. Everything else — the parser, the server, the
linter, and every client — is built around it.
toboggan/
├── toboggan-core/ # Domain model (Talk, Slide, Content, Command, …)
├── toboggan-stats/ # Word/step/image counts and HTML inspection
├── toboggan-cli/ # Folder parser + renderers (toml/json/yaml/html/typst) + thumbnails
├── toboggan-server/ # Axum WebSocket/REST server, homepage, presenter view, PDF, guide
├── toboggan-lint/ # Library-first presentation linter (rules + LintReport)
├── toboggan-mcp/ # rmcp stdio MCP server (outline/stats/lint/scaffold/mutations)
├── toboggan-client/ # Shared client library: connection, reconnection, dispatch
├── toboggan-tui/ # Terminal client using ratatui
├── toboggan-desktop/ # Native desktop client using iced
├── toboggan-mobile/ # iOS/Android Rust library with UniFFI bindings
└── toboggan/ # The one binary in the workspace; dispatches to all of the above
Companion directories outside the Cargo workspace:
├── toboggan-web/ # TypeScript + WASM web client (built into the embedded dist)
├── TobogganApp/ # Native iOS app (SwiftUI)
├── toboggan-android/ # Android host app for the mobile crate
└── toboggan-py/ # Python bindings (excluded from the workspace)
Clients and server exchange JSON over /api/ws: a client sends a Command, the
server broadcasts a Notification to everyone. The authoritative list is the
code — Command and
Notification — and the REST surface is
documented at /doc on a running server, or via toboggan openapi.
A session in outline:
A client offers a token; it never claims a role. The server decides, and tells
the client what it got in Registered.
- Rust 1.96+ (2024 edition)
- Node.js 22+ and
pnpm(for the web client) mise(optional, for task automation)typst(optional, forpdf; and forthumbnailswhen no browser is found)- Chrome, Chromium or Edge (optional, for
thumbnails): the slide overview is photographed from the real deck, so the pictures match the projector
mise check # fmt + clippy + nextest, root workspace — run this before pushing
mise build:web # rebuild the embedded web dist (wasm-pack + vite)
mise serve # build + serve examples/riir-folder with live reload
cargo +nightly fmt --all # the repo formats on nightly
cargo clippy --all-targets --all-features -- -D warnings
cargo nextest run
cargo test --docThe web client is a separate Cargo workspace, so --workspace from the root
does not reach it:
cd toboggan-web/toboggan-wasm
cargo clippy --all-targets --target wasm32-unknown-unknown -- -D warningsSee CONTRIBUTING.md before opening a pull request — in
particular the note about prek hooks, which are git hooks and therefore do
not run under jj.
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Built with excellent Rust crates, including:
Core — tokio, axum, serde, anyhow, miette, comrak, clap, tracing, jiff, toml
Clients — wasm-bindgen, gloo, rioterm, ratatui, crossterm, iced, uniffi
Networking — tokio-tungstenite, reqwest, tower-http
And many more that make Rust development a joy.