stardeck 0.1.0

Developer-first presentation tool - Slidev for Python

StarDeck

Developer-first presentation tool for Python. Write slides in Markdown, present with a reactive UI powered by StarHTML and Datastar.

Features

• Markdown slides — Write in familiar Markdown with --- separators
• Click animations — Progressive reveal, hide, swap, bulk wrap, and explicit ranges with Motion-powered animations
• Layouts — cover, center, two-cols, three-cols, grid, quote, section, steps, and more
• Region tags — <left>, <right>, <item>, <step> for structured layouts
• Inline HTML + Tailwind — Use any HTML with Tailwind CSS v4 classes in your slides
• Presenter mode — Speaker notes, timer, next-slide preview, drawing tools
• Live reload — Edit slides, see changes instantly with --watch
• Keyboard navigation — Arrow keys, Space, grid overview (G/O)
• Static export — Self-contained HTML output, no server required
• Tunnel sharing — Share presentations publicly with --share
• Themes — Dark and light themes, themeable with CSS variables

Quick Start

pip install stardeck

Create slides.md:

---
title: My Presentation
---

# Hello World

My first slide

---

## Second Slide

- Point one
- Point two

<click>Revealed on click</click>

---
layout: two-cols
---

<left>

## Left Column

Content here

</left>

<right>

## Right Column

More content

</right>

Run it:

stardeck run slides.md

Usage

# Run with live reload
stardeck run slides.md --watch

# Run with a theme
stardeck run slides.md --theme light

# Run with public tunnel
stardeck run slides.md --share

# Export to static HTML
stardeck export slides.md --output dist/

Slide Authoring

Frontmatter

Each slide can have YAML frontmatter for configuration:

---
layout: cover
transition: slide-left
background: "#2563eb"
class: items-center justify-center
---

The first slide's frontmatter also sets deck-wide options: title (page title), transition (default transition), and click animation defaults (click-animation, click-duration, click-delay, click-ease, click-spring).

Click Animations

Wrap content in <click> tags for progressive reveal:

<click>First point appears</click>
<click>Then the second</click>
<click>Finally the third</click>

Press arrow keys or Space to step through clicks before advancing to the next slide.

Click reveals are powered by the Motion animation library in server mode, with spring physics and configurable presets.

Available presets: fade (default), slide-up, slide-down, slide-left, slide-right, scale, bounce.

Animation attributes

Set the animation per-click with inline attributes:

<click animation="slide-up">Slides up into view</click>
<click animation="scale" duration="500">Slow scale-in</click>
<click animation="bounce" spring="bouncy">Bouncy entrance</click>

Attribute	Description	Example
animation	Preset name	animation="slide-up"
duration	Duration in ms	duration="500"
delay	Delay before animation in ms	delay="200"
ease	CSS easing function	ease="ease-in-out"
spring	Spring physics preset	spring="bouncy"

Spring presets: gentle, bouncy, tight, slow.

Custom transforms

Override presets entirely with individual transform properties:

<click x="30" opacity="0">Slide in from right with fade</click>
<click y="-20" scale="0.8">Drop in and grow</click>
<click rotate="10" opacity="0">Rotate in</click>

Properties: x, y, scale, rotate, opacity. When any transform property is set, the preset is bypassed.

Exit animations

Control how elements animate out when stepping backwards:

<click exit-opacity="0" exit-duration="200">Fast fade out on reverse</click>

Exit attributes mirror enter attributes with an exit- prefix: exit-duration, exit-delay, exit-ease, exit-spring, exit-x, exit-y, exit-scale, exit-rotate, exit-opacity.

Per-slide and deck-wide defaults

Set defaults via frontmatter — per-slide overrides deck-wide:

---
click-animation: slide-up
click-duration: 400
click-spring: gentle
---

Deck-wide defaults go in the first slide's frontmatter. Per-slide frontmatter overrides them. Inline attributes on individual <click> tags override both.

Same-step reveals with <after>

<after> shares the same click step as the preceding <click>:

<click>Main point (click 1)</click>
<after>Also appears at click 1</after>
<after>This too (click 1)</after>

<click>Next point (click 2)</click>
<after>Also at click 2</after>

Hide on click

<click hide> starts visible and disappears on its click step:

<click hide>This vanishes at click 1</click>
<after>This replaces it at click 1</after>

A <click hide> followed by <after> creates a swap — the hide and reveal animate together in-place.

Bulk reveals with <clicks>

<clicks> wraps each paragraph in a <click> tag automatically:

<clicks animation="slide-up">

First point

Second point

Third point

</clicks>

Attributes on <clicks> cascade to all children. Equivalent to writing three separate <click animation="slide-up"> tags.

Explicit numbering with at=

Pin elements to specific click numbers or visibility ranges:

<click at="3">Appears at click 3</click>
<click at="2-4">Visible during clicks 2–3, gone at 4</click>

Sequential <click> tags and explicit at= numbering are independent — max_clicks is the maximum of both. Ranges can overlap.

Speaker Notes

Add notes inside HTML comments with the notes keyword:

# My Slide

Content here

<!-- notes
These notes appear in presenter mode only.
Multiple note blocks per slide are supported.
-->

Backgrounds

Set solid colors or images via frontmatter:

---
background: "#2563eb"
---

---
background: assets/hero.jpg
---

Images

Standard Markdown images work. Place files in an assets/ directory next to your slides — it's auto-mounted during serve and auto-copied on export:

![diagram](assets/architecture.png)

For image-based layouts, use the image frontmatter key:

---
layout: image-left
image: assets/photo.jpg
---

Inline HTML & Tailwind

Raw HTML with Tailwind classes works directly in slides:

<div class="text-blue-500 text-4xl p-8 rounded-lg bg-blue-500/10">
  Styled with Tailwind v4
</div>

The cls= alias is also supported (StarHTML convention): <div cls="text-red-500">.

You can also add classes to entire slides via frontmatter:

---
class: items-center justify-center text-center
---

Layouts

Set layouts in slide frontmatter:

---
layout: cover
---

Available layouts: default, cover, center, section, quote, fact, statement, full, two-cols, three-cols, grid, steps, comparison, sidebar-left, sidebar-right, image-left, image-right, hero, caption.

Region Tags

Multi-column and structured layouts use region tags:

---
layout: two-cols
---

<left>
Left content
</left>

<right>
Right content
</right>

Available tags: <left>, <right>, <top>, <bottom>, <main>, <sidebar>, <item>, <step>.

The grid layout supports custom columns with cols:

---
layout: grid
cols: 3
---

<item>Card 1</item>
<item>Card 2</item>
<item>Card 3</item>

Transitions

Set per-slide transitions in frontmatter, or set a default in the first slide:

---
transition: slide-left
---

Available: fade (default), slide-left, slide-right, slide-up, slide-down.

Themes

Two built-in themes:

• default — Dark theme with teal accents (Monokai-inspired code highlighting)
• light — Light theme with teal accents (GitHub-inspired code highlighting)

stardeck run slides.md --theme light
stardeck export slides.md --theme light

Themes are CSS files in stardeck/themes/. Override CSS variables to customize:

.stardeck-root {
    --accent: #8b5cf6;
    --bg-dark: #0a0a0a;
    --bg-slide: #171717;
    --text-primary: #e4e4e7;
    --text-heading: #fafafa;
}

Utility Classes

Themes provide presentation-specific utility classes:

• Typography: text-hero, text-title, text-subtitle, text-body, text-small, text-caption
• Color: text-accent, text-heading, text-muted
• Padding: slide-p-0, slide-p-sm, slide-p-lg

Presenter Mode

When you run stardeck run, the CLI prints a presenter URL with an auth token:

Presenter: http://localhost:5001/presenter?token=abc123

The presenter view includes:

• Current slide with drawing tools (pen, shapes, arrows)
• Next slide preview
• Speaker notes
• Elapsed timer
• Keyboard navigation (same as audience view)

Drawings sync to the audience view in real time.

URL Hash Navigation

URLs update to #slide.click format (e.g., #3.2 for slide 3, click 2). Share links to specific slides, and browser back/forward buttons work.

Development

git clone https://github.com/banditburai/stardeck.git
cd stardeck
uv sync --all-extras

uv run pytest                  # tests
uv run ruff check              # lint
uv run ruff format --check     # format
uv run pyright                 # type check

License

Apache 2.0 — see LICENSE for details.