StellarDeck

Convention-first, agent-first markdown presentations.

Write content, get layouts. StellarDeck infers slide structure from what you write — no directives needed. The same .md file renders in a desktop app, a browser, an embeddable viewer, or the CLI. When you need more control, Deckset-compatible markdown and custom directives are there.

If you're coming from Deckset, Marp, or Reveal.js, see the comparison for when to use what.

Four ideas shape the project:

Storytelling. A deck is a sequence of moments. Markdown's constraints (one file, short slides, linear order) keep focus on what you're saying. Reading through the deck feels like reading a script.

Autoflow. Reads each slide's content and picks a layout — 9 rules, zero configuration. A slide with four short lines gets a Z-pattern. An image with a few words becomes a hero background; with more text it takes one side of a split, alternating across the deck. Consecutive slides don't repeat the same treatment (anti-monotony). Explicit directives always win.

Agent-native. Markdown is what LLMs produce. The CLI takes stdin, exports PDF/PNG/grid, previews in the browser, validates diagnostics, and emits structured JSON. The stellardeck skill converts source text (blog posts, transcripts, meeting notes) into scored slide decks.

Simple. stellardeck --preview deck.md and you're presenting. No build step, no bundler. The .md file is the artifact, PDFs are regenerable.

9 themes, up to 7 color schemes each, dark and light.

Try it

Six example decks you can navigate and edit live — right in your browser:

Learn the features:

• Getting Started — headings, images, splits, code blocks
• Kitchen Sink — every supported feature in one deck
• Autoflow — zero-config layout inference in action

See it in action (real talks):

• Bean to Bar Chocolate — diagrams, columns, custom backgrounds
• Hand Balancing — split layouts with portraits
• Vibe Coding — a keynote about AI and coding

Quick start

CLI — one command to a running deck:

npm install -g stellardeck
stellardeck --demo                # presents a sample deck in your browser
stellardeck --preview deck.md     # your own deck, live

Exports need a headless browser, installed once:

npx playwright install chromium
stellardeck deck.md               # → deck.pdf (also --png, --grid, --validate)

Desktop app (macOS, Apple Silicon): download the .dmg from the latest release, drag to Applications, drop a .md into the window. First launch: right-click → Open (not code-signed yet).

Sample decks (images included): stellardeck-demo-decks.zip

From source:

git clone https://github.com/peas/stellardeck.git
cd stellardeck
npm install
npm run preview -- demo/getting-started.md

Desktop app (Electron)

npm install
npm run electron -- demo/getting-started.md

For a packaged build (correct app name in the macOS menu bar, distributable via .dmg):

npm run app -- demo/getting-started.md   # packages on first run, caches after
npm run make                              # produces out/make/dmg/… + out/make/zip/…

Built with Electron + electron-forge. No Rust toolchain required.

CLI

# Live
npm run preview -- deck.md                           # open in browser, Ctrl+C stops
npm run export -- --serve                            # dev server + viewer

# Export
npm run export -- deck.md                            # → deck.pdf
npm run export -- --png deck.md                      # → deck-slides/001.png, 002.png...
npm run export -- --grid deck.md                     # → deck-grid.png
npm run export -- --input-dir decks --output dist    # batch

# Inspect
npm run export -- --validate deck.md                 # diagnostics without export
npm run export -- --list-themes                      # available themes (JSON)
npm run export -- --list-schemes alun                # color schemes for a theme

# Agent
npm run export -- --json --pdf deck.md               # machine-readable output
cat deck.md | npm run export -- --pdf - out.pdf      # stdin
npm run export -- --help                             # full reference

Format

StellarDeck uses Deckset-compatible markdown. See format-spec.yaml for the full 66-feature spec.

footer: My Talk
slidenumbers: true

#[fit] Hello, World

---

![right](photo.jpg)

# Split Layout

Text on the left, image on the right.

---

[.background-color: #1e3a5f]

#[fit] Custom Colors

Testing

npm test              # 318 unit tests (~3s)
npm run test:e2e      # 70 E2E tests (Chromium)
npm run test:layout   # 32 layout + consistency tests
npm run test:export   # 40 CLI integration tests
npm run test:visual   # 18 visual regression tests
npm run test:all      # all of the above

License

MIT — see LICENSE.

Built by Paulo Silveira.