# 🎬 keynote-deck
**Turn markdown into beautiful, native Keynote presentations — with Claude Code.**
Write a lesson, a talk, or an outline in markdown. Ask Claude for a deck. Get
a real `.key` file — built on *your* branded master slides, with
syntax-highlighted code panels, presenter notes ready to read on camera, and
preview images so Claude can quality-check every slide before handing it over.
No PowerPoint intermediate. No import fidelity loss. No dragging text boxes at
11pm before a presentation.
```
deck.md ──▶ generate.sh ──▶ Keynote (AppleScript + md2key) ──▶ deck.key + previews
```
## Why native Keynote?
Most AI slide tools emit `.pptx` and hope for the best. Keynote's importer
then substitutes fonts, drops effects, and shifts layouts. This skill drives
Keynote itself through AppleScript, so what you get is what Keynote renders:
native slides, native text, your masters, zero conversion tax — plus
everything Keynote is great at afterwards (builds, animations, video export).
## What it does
- **Markdown in, deck out** — headings become slides, mapped to your named
master slides; bullets, nested bullets, tables, and images all supported
- **Beautiful code slides** — fenced code blocks render syntax-highlighted on
a clean 1740×800 panel, positioned consistently every time
- **Presenter notes from `^ lines`** — write your narration inline; perfect
for course creators recording voiceover
- **Light/dark slide variants** — heading levels select masters, so decks can
run all-light, all-dark, or alternate per slide
- **Self-verifying** — every run exports preview PNGs; Claude inspects them
for overflow and tightens the content before calling it done
- **Self-healing** — the two small md2key patches it depends on are re-applied
automatically if the gem is ever updated
## Quick start
```bash
# 1. Install the skill
git clone https://github.com/markshust/claude-code-skill-keynote-deck.git \
~/.claude/skills/keynote-deck
# 2. Install dependencies (Homebrew: https://brew.sh)
brew install ruby highlight
/opt/homebrew/opt/ruby/bin/gem install md2key
# 3. Build your branded template (one time, 15–90 min)
# Follow TEMPLATE-GUIDE.md — quick path or fully custom brand path.
# Save it to ~/.claude/skills/keynote-deck/templates/default.key
```
Then, in Claude Code:
> *"Create a Keynote deck from lessons/03-networking.md"*
Or run it directly:
```bash
~/.claude/skills/keynote-deck/scripts/generate.sh examples/example-deck.md
```
First run: macOS will ask to allow your terminal to control Keynote — click
**Allow**. Don't click around in Keynote while a deck is generating; the
pipeline drives the frontmost document.
## Writing decks
````markdown
# Deck Title ← cover slide
Subtitle line
## What you'll learn ← light content slide
- Bullet one
- Bullet two
- Nested bullet
^ Presenter note — your narration script for this slide.
### The code ← dark code slide
```bash
echo "hello"
```
#### Key takeaways ← dark content slide
##### More code ← light code slide
````
| Markdown | Master | Role |
|----------|--------|------|
| `#` (first) | `cover` | cover |
| `#` (mid-deck) | `h1` | section divider |
| `##` | `h2` | content — light |
| `###` | `h3` | code — dark |
| `####` | `h4` | content — dark |
| `#####` | `h5` | code — light |
Try it: `examples/example-deck.md` exercises every slide type.
## Your template = your brand
The skill's superpower is the split: **markdown owns the content, your
Keynote template owns every pixel of design.** Build the template once —
masters named `cover`, `h1`–`h5` — and every future deck is automatically
on-brand.
[`TEMPLATE-GUIDE.md`](TEMPLATE-GUIDE.md) walks through both paths:
- **Quick** — adapt any built-in Keynote theme in ~15 minutes
- **Fully custom** — the method this skill was built with: design each
master's background as an HTML/SVG artboard with Claude (starter files in
`templates/design-starter/`), render at 2× with headless Chrome, assemble
in Keynote, and iterate on the HTML sources forever
## Requirements
- macOS with Keynote (Mac App Store)
- [Homebrew](https://brew.sh), Ruby (`brew install ruby`), the
[`md2key`](https://github.com/k0kubun/md2key) gem, and
[`highlight`](https://gitlab.com/saalen/highlight) (`brew install highlight`)
- Claude Code (for the AI-driven workflow; `generate.sh` also works standalone)
- Optional: `@mermaid-js/mermaid-cli` for ` ```mermaid ` diagram blocks
## Troubleshooting
- **"md2key missing"** — `/opt/homebrew/opt/ruby/bin/gem install md2key`
(system Ruby is too old for md2key's dependencies)
- **Unbranded white slides** — no template found; check
`~/.claude/skills/keynote-deck/templates/default.key`, or point
`$KEYNOTE_DECK_TEMPLATE` at one, or drop `keynote-template.key` in your project
- **Placeholder prompt text on code slides** — delete the body placeholder
from your `h3`/`h5` masters (unfilled placeholders export their prompt text)
- **Keynote hangs on save** — known autosave quirk; the script already uses
the safe save path. If Keynote is wedged: force-quit, relaunch, rerun.
## Credits
Created by [Mark Shust](https://markshust.com).
Standing on the shoulders of [md2key](https://github.com/k0kubun/md2key) by
Takashi Kokubun.
## License
[MIT](LICENSE)