slide-deck

slide-deck is a repo-level presentation workflow for Claude Code: a skill, theme system, and build pipeline for turning natural-language requests into polished slide decks.

It is built around a fast loop:

• author in Marp-flavored Markdown
• build to self-contained HTML
• iterate in a live preview with notes and keyboard shortcuts
• optionally export PDF and PPTX from the same source deck

Table of Contents

• Showcase
• Why slide-deck
• Features
• Requirements
• Install
• Quick Start
• Preview Controls
• Authoring Model
• Documentation
• Repo Layout
• Status
• License and Notice

Showcase

A few example slides rendered from the repo's built-in themes and slide types.

Title Slide

Comparison Slide

Code Slide

Why slide-deck

This repo is aimed at people who want developer-friendly slide authoring without manually building a full frontend stack for every presentation.

The core design goals are:

• keep the source format simple for both humans and LLMs
• separate structure (slide types) from visuals (themes)
• make HTML the primary deliverable
• keep iteration fast enough for conversational deck building

If you are using Claude Code / Cursor, this repo also includes SKILL.md so the workflow can be driven directly from the assistant.

Features

• 10 reusable slide types: title, content, stat, quote, comparison, architecture, diagram, image, code, thankyou
• 8 shipped themes, including Catppuccin and a conference-style deck theme
• Mermaid fenced blocks rendered to SVG before Marp compilation
• Self-contained HTML output with post-processed navigation, notes panel, and local image inlining
• Best-effort PDF and PPTX export from the same source deck
• Live preview mode with auto-rebuild
• Vim-style navigation aliases in HTML preview: h/j/k/l

Requirements

Core:

• node >= 18
• npm

Preview mode (--serve) also requires:

• uv
• inotifywait on Linux or fswatch on macOS

Notes:

• Mermaid support relies on @mermaid-js/mermaid-cli, which is installed as an optional npm dependency
• PDF/PPTX export intentionally enables local-file access so generated Mermaid SVGs and local assets can be included

Install

npm install

If you plan to use live preview:

• Linux: install inotify-tools
• macOS: install fswatch
• install uv from Astral's docs

Quick Start

Build the bundled example deck:

bash scripts/build.sh test/all-slide-types.md

Start live preview with auto-rebuild:

bash scripts/build.sh test/all-slide-types.md --serve

Then open:

http://localhost:8080/all-slide-types.html

Export HTML + PDF + PPTX:

bash scripts/build.sh test/all-slide-types.md --pdf --pptx

Preview Controls

In the HTML preview:

• Left / Right arrows move between slides
• h / l and j / k act as vim-style navigation aliases
• N toggles the notes overlay

HTML is the primary output. PDF and PPTX are supported, but they are best-effort exports and do not include the HTML-only runtime behaviors.

Authoring Model

Decks are written in Marp-flavored Markdown with small structural HTML fragments for richer layouts.

Examples:

---
marp: true
theme: minimal-dark
paginate: false
---

<!-- _class: title -->

# Build _Developer-Friendly_ Decks

<!-- notes: Emphasize the fast edit-build-refresh loop here. -->

```mermaid
graph LR
    A[Prompt] --> B[Markdown] --> C[HTML/PDF/PPTX]
```

Typical workflow:

1. Ask for audience, tone, theme, and approximate deck length.
2. Draft slide headlines first.
3. Write the deck Markdown with Marp frontmatter and _class slide directives.
4. Run bash scripts/build.sh deck.md --serve.
5. Iterate on the .md while the preview rebuilds automatically.
6. Export --pdf and/or --pptx when needed.

Documentation

The repo includes focused authoring references:

• references/marp-syntax.md
• references/slide-types.md
• references/theming.md

Key repo components:

• SKILL.md: Claude Code skill definition
• scripts/: build pipeline, post-processor, and Mermaid preprocessor
• themes/: shipped themes plus dynamic theme support
• test/: example decks and verification fixtures

Repo Layout

slide-deck/
|- README.md
|- SKILL.md
|- scripts/
|- themes/
|- references/
|- templates/
|- docs/
`- test/

Status

slide-deck is designed as an HTML-first deck workflow for Claude Code / Cursor use cases, with PDF and PPTX provided as convenience exports.

License and Notice

• Licensed under the MIT License
• Trademark / branding notice: see NOTICE.md