Getting Started

Install

Pick the track that matches how you work. Each one gets you from zero to a rendered deck in under a minute.

Desktop app (macOS)

1. Download StellarDeck-0.9.0-arm64.dmg (Apple Silicon)
2. Drag StellarDeck to Applications
3. First launch: right-click → Open (the app isn’t code-signed yet, so macOS asks once)
4. Drop any .md file into the window — you’re presenting

Arrow keys navigate, G opens the grid view, P opens presenter mode.

CLI

npm install -g stellardeck
npx playwright install chromium   # one-time: the headless renderer

Then, from any directory:

stellardeck deck.md               # → deck.pdf
stellardeck --preview deck.md     # live preview in your browser
stellardeck --help                # PNG, grid, batch, validate, themes

From source

For contributors, or if you want the browser viewer without installing anything globally:

git clone --branch v0.9.0 https://github.com/peas/stellardeck.git
cd stellardeck
npm install
npm run preview -- demo/bean-to-bar-chocolate.md

Run a sample

Grab the sample decks (three complete presentations, images included) from the release:

curl -L -o demo.zip https://github.com/peas/stellardeck/releases/latest/download/stellardeck-demo-decks.zip
unzip demo.zip
stellardeck --preview demo/bean-to-bar-chocolate.md

Or open demo/bean-to-bar-chocolate.md in the desktop app. Other samples: demo/hand-balancing.md, demo/vibe-coding.md.

Start from scratch

Create a file called my-deck.md:

# Hello World

Welcome to StellarDeck.

---

# Second Slide

That's it — `---` separates slides.

Then preview it:

stellardeck --preview my-deck.md

(In the desktop app: just drop the file into the window. From a repo checkout: npm run preview -- my-deck.md.)

Markdown syntax

StellarDeck turns plain markdown into presentation slides. Write text, separate with ---, and you have a deck.

Slide Structure

Frontmatter at the top configures the deck. --- on its own line separates slides.

slide.md

footer: stellardeck.dev
slidenumbers: true

# My First Slide

Welcome to StellarDeck.

Headings

Use #, ##, ### for heading levels.

slide.md

# Main Title

## Subtitle

### Section heading

Regular text below headings.

Auto-fit Headings

Add [fit] after # to make headings stretch to fill the slide width.

slide.md

#[fit] Auto-fit Headings

^ Add [fit] after # to make headings fill the slide width.

Lists

Unordered lists use -, ordered use 1.. Nest with two spaces.

slide.md

# Shopping List

- Apples
- Bananas
- Yellow ones
- Green ones
- Oranges

1. First step
2. Second step

Blockquotes

Use > for blockquotes. They render with an accent-colored left border.

slide.md

> The best way to predict
> the future is to invent it.
> — Alan Kay

Speaker Notes

Lines starting with ^ become speaker notes — invisible on the slide, visible in presenter mode (P).

slide.md

# Key Point

The important thing to remember.

^ This note is only visible in presenter mode. The audience never sees it.

Build Lists

[.build-lists: true] reveals list items one at a time on click.

slide.md

[.build-lists: true]

# Agenda

- Introduction
- Main topic
- Conclusion

Presenter Mode

Press P in the desktop app to open a presenter window with the current slide, next slide preview, and speaker notes. Here’s what it looks like:

Current

Next

Speaker Notes

No notes for this slide.

Navigate with the arrows — the next slide preview and notes update automatically. In the desktop app, the presenter window syncs with the main window via BroadcastChannel.

Next Steps

Images & Layouts Split layouts, backgrounds, columns, and positioning.

Code, Math & Diagrams Syntax highlighting, KaTeX, Mermaid, QR codes.

Autoflow Zero-config layout inference.

Themes & Colors Built-in themes and per-slide color overrides.