From Markdown to Slide Deck: Build Presentations Entirely in Your Terminal

The Problem: Slides Are Where Productivity Goes to Die

It is 11 PM on a Sunday. You have a presentation tomorrow. The content exists -- research notes, a design doc, maybe a draft blog post. The hard part is not what to say. The hard part is the two hours you are about to lose wrestling PowerPoint into submission.

You drag a text box three pixels to the right. You undo. You drag it two pixels. You fight bullet point indentation that seems to have a personal grudge against you. You scroll through forty-seven slide transition effects, each more distracting than the last, and settle on "None" -- which is what you should have picked ten seconds ago.

Then your co-presenter asks for changes. You open deck_final_v3_ACTUAL_final.pptx, make edits, email it to three people. Now four copies exist, diverging like parallel universes that will never reconcile. There is no diff. There is no merge. There is no history. Just chaos wearing a .pptx extension.

Presentations have three problems: version control, tooling, and content structure. All three are solvable with tools already sitting in your terminal.

Think of it like this. You would never write code in a WYSIWYG editor, email .js files to your team, and track versions with filename suffixes. That would be insane. Yet that is exactly how most people build presentations.

This article shows the complete alternative: write slides in Markdown, use Claude Code to structure content and generate speaker notes, render to PDF/HTML/PPTX with Marp CLI, preview live while editing, and track every revision in git.

The Stack: Marp CLI + Claude Code + Git

The presentation workflow rests on three pillars. Each handles one job. Together, they replace everything PowerPoint does -- minus the frustration.

Marp CLI (@marp-team/marp-cli) is a converter. Feed it a Markdown file, and it produces a slide deck. Each --- separator becomes a new slide. It renders to PDF, HTML, and PPTX. It supports themes, custom CSS, background images, and speaker notes. The killer feature is --watch mode: change the source file, and the output regenerates instantly. Think of it as hot-reload for presentations.

Claude Code handles the intellectual labor -- the part that takes the longest when done manually. It structures raw notes into a coherent narrative, writes speaker notes for each slide, and enforces best practices like one idea per slide, minimal text, and concrete examples. It is your presentation co-author who never gets tired and never argues about font sizes.

Git does what git always does. It tracks every change, enables branching for different audiences, and makes collaboration possible without deck_v4_johns_edits.pptx. Your slides become code. Code has diffs. Diffs have meaning.

Install the Stack

npm install -g @marp-team/marp-cli

That is the only install. Claude Code and git are already on your machine.

Step 1: Structure Raw Content into Slides

Start with your raw material. Notes from a brainstorming session. A document outline. An existing blog post. Even a voice memo transcript. Dump it into a file -- polish comes later.

cat > raw-notes.md << 'EOF'
Topic: Why Engineering Teams Should Adopt Git Worktrees

Key points:
- Context switching between branches kills flow state
- git worktree creates parallel working directories from one repo
- Each worktree has its own HEAD, index, working tree
- Combined with AI CLI agents, enables true parallel development
- Setup takes 5 minutes, saves hours per week
- Adoption barrier is low: one new git command

Target audience: Engineering leads, senior developers
Presentation length: 10-15 minutes
EOF

Now let Claude Code transform this pile of bullets into a Marp-formatted slide deck. The prompt is specific -- it tells the agent the format, the constraints, and the quality bar for speaker notes.

claude -p "
Read raw-notes.md. Create a Marp-formatted presentation in slides.md.

Rules:
- Use '---' to separate slides. First slide is the title slide.
- Add 'marp: true' in the YAML frontmatter.
- One core idea per slide. Maximum 5 bullet points per slide.
- Include speaker notes under each slide using Marp comment syntax.
- Write speaker notes as if coaching the presenter: what to emphasize, where to pause, what question the audience might ask.
- Target 12-15 slides for a 10-15 minute talk.
- End with a clear call-to-action slide and a Q&A slide.
"

Claude Code reads the raw notes, understands the topic structure, and produces a complete Marp file. Here is what the output looks like.

---
marp: true
theme: default
paginate: true
---

# Git Worktrees: Parallel Development Without the Pain

**Engineering Productivity Series**
Danny Huang | March 2026

<!-- speaker notes: Open with a question to the audience: "How many times did you run git stash this week?" Let them think about it. Most will say 3-5 times. That is the pain point you are solving. -->

---

## The Cost of Context Switching

- Average developer switches branches **5-10 times/day**
- Each switch: stash, checkout, rebuild, re-orient
- **15-25 minutes** to recover deep focus after interruption
- 5 switches x 20 min = **~2 hours lost daily**

<!-- speaker notes: These numbers come from the Microsoft Research study on developer productivity. Pause after the 2 hours number. Let it sink in. Someone will visibly react. -->

---

## What If You Never Switched Branches Again?

```bash
git worktree add ../feature-auth main
git worktree add ../hotfix-api release/2.1
```

Two commands. Two separate working directories. Same repository.

<!-- speaker notes: This is the "aha" moment. Show the terminal. Run the commands live if possible. The audience needs to see how trivially simple this is. -->

---

Notice what the speaker notes are doing. They are not just repeating the bullet points out loud. They are coaching: where to pause, what reaction to expect, whether to run a live demo. That is the difference between notes you actually use and notes you skip.

Step 2: Configure Presentation Style in CLAUDE.md

A good presentation style is like a good code style guide. You define it once, and every future deck follows the same rules automatically.

Add a presentation section to your project's CLAUDE.md. This tells Claude Code how to build every deck -- so you encode your taste once and the agent enforces it forever.

## Presentation Style Guidelines

### Slide Content
- One idea per slide. If you need a second idea, make a second slide.
- Maximum 5 bullet points. Prefer 3.
- Every slide must pass the "squint test": readable from the back of the room.
- No full sentences on slides. Fragments and keywords only.
- Code blocks: maximum 6 lines. Highlight the one line that matters.

### Speaker Notes
- Write for a nervous presenter, not a confident one.
- Include: what to say, what to emphasize, what to skip if running short.
- Note likely audience questions and suggested answers.
- Mark optional slides with [SKIP IF SHORT].

### Structure
- Slide 1: Title + speaker credibility (one line).
- Slide 2: The problem. Make the audience feel the pain.
- Slides 3-N: The solution, building incrementally.
- Slide N-1: Concrete call-to-action. Not "learn more" -- a specific next step.
- Slide N: Q&A with 2-3 pre-loaded questions the presenter can seed.

### Visual Direction
- Marp theme: default or gaia.
- Use Marp backgroundColor directive for emphasis slides.
- One image per slide maximum. Images must earn their place.

Think of CLAUDE.md as a style.config for your presentations. You would not let every developer on your team pick their own linting rules. Same idea here. Define the rules once. Let the agent enforce them every time.

Step 3: Render and Preview with Marp CLI

Marp CLI converts your Markdown to presentation formats. One command per format.

# Render to HTML (fastest, good for preview)
marp slides.md -o slides.html

# Render to PDF (for distribution)
marp slides.md -o slides.pdf

# Render to PowerPoint (for organizations that require it)
marp slides.md -o slides.pptx

The real power is --watch mode. It monitors the Markdown file and regenerates the output on every save -- like a live-reload server for your slides.

marp slides.md -o slides.html --watch

This opens a browser window that updates in real time. Every time you save the Markdown file, the browser refreshes within a second. You see exactly what your audience will see while you are still typing in your editor. No "preview" button. No build step. Just save and see.

Step 4: The Live Editing Loop

This is where the workflow stops feeling like work and starts feeling like a superpower.

Open two terminal panes side by side. Left pane: your editor (vim, neovim, nano, whatever you think with) with slides.md open. Right pane: marp slides.md -o slides.html --watch running, with the HTML output open in a browser.

Edit a slide on the left. Save. The right pane updates instantly. You see the rendered result without switching windows, without clicking "preview," without waiting for anything. It is the tightest feedback loop a presenter can have -- tighter than any GUI tool, because there is nothing between your thought and the output except a keystroke.

Need to restructure a section? Ask Claude Code.

claude -p "
Read slides.md. Slides 5-8 cover git worktree internals. They are too detailed
for this audience (engineering leads, not kernel developers). Condense slides
5-8 into two slides: one covering the mental model, one covering the three
commands they need. Update speaker notes accordingly. Write the result back
to slides.md.
"

Save. The right pane updates. You see the condensed version immediately. The feedback loop is measured in seconds, not minutes.

Step 5: Generate Speaker Notes in Bulk

Here is a scenario that happens constantly: you have slides but no speaker notes. Maybe you built the deck in a rush. Maybe you imported slides from an existing presentation. Maybe you are the kind of person who thinks "I will just wing it" and then regrets it at the podium.

Claude Code can generate or upgrade notes for every slide at once.

claude -p "
Read slides.md. For every slide that lacks speaker notes, generate them.

For every slide that already has speaker notes, review and improve them:
- Add timing estimates (e.g., 'spend 60 seconds here').
- Add transition phrases to the next slide.
- Note where to make eye contact, where to gesture at the screen.
- Flag slides that could be cut if the talk runs long.

Write the updated file back to slides.md.
"

Writing good speaker notes manually for a 15-slide deck takes 30-45 minutes. Claude Code does it in one pass. And because it sees the entire deck structure at once, it writes notes that flow from slide to slide -- transitions, callbacks to earlier points, timing that actually adds up to your target duration. A human writing notes slide-by-slide rarely achieves that coherence.

Step 6: Build a Reusable Presentation Skill

If you make presentations more than once a quarter, automate the process further. Save a reusable skill file at .claude/skills/presentation-builder.md in your project.

# Skill: Presentation Builder

## Trigger
When the user asks to create, edit, or restructure a presentation.

## Inputs
- Raw content file (notes, outline, blog post, or existing slides)
- Target audience
- Time constraint (e.g., "10 minutes", "lightning talk", "keynote")

## Process
1. Read the source material and identify the core narrative arc.
2. Structure into Marp-formatted slides following CLAUDE.md guidelines.
3. Generate speaker notes for every slide.
4. Add timing estimates that sum to the target duration.
5. Write output to slides.md (or specified filename).
6. Run `marp slides.md -o slides.html` to verify rendering.

## Output Format
- Marp-compatible Markdown with YAML frontmatter
- Speaker notes in HTML comment syntax
- One file, ready to render

## Quality Checks
- Total slide count reasonable for time constraint (~1 slide per minute)
- No slide has more than 5 bullet points
- Every slide has speaker notes
- Code blocks are under 6 lines
- Title slide includes speaker name and date

A skill is like a Makefile for a specific job. With this in place, future presentations start with a single command. Claude Code reads the skill, follows the recipe, and produces a ready-to-render deck. You go from raw notes to polished slides without explaining the process each time.

Step 7: Version Control for Presentations

Because your slides are plain Markdown, git works perfectly. And that changes everything.

git init presentations
cd presentations
git add slides.md
git commit -m "Initial deck: git worktrees for engineering leads"

Now you can do things that PowerPoint literally cannot do.

Branch for different audiences. The same core deck, adapted for engineers versus executives. Like maintaining a library with different API surfaces for different consumers.

git checkout -b audience/executives
claude -p "
Read slides.md. This version is for VP-level executives, not engineers.
Remove all code blocks. Replace technical details with business impact metrics.
Keep the narrative arc intact. Update speaker notes for a non-technical audience.
"
git add slides.md
git commit -m "Adapt deck for executive audience"

Diff your changes. See exactly what changed between versions, line by line.

git diff main..audience/executives -- slides.md

Tag versions for specific events. Never wonder which version you presented at which conference.

git tag "devcon-2026-march"

Collaborate without file duplication. Your co-presenter clones the repo, makes edits, opens a pull request. You review the diff. No email attachments. No "which version is current?" Just the same workflow you already use for code.

The Complete Workflow Script

Here is a single script that takes raw notes and produces a ready-to-present deck in three formats.

#!/bin/bash
set -euo pipefail

SOURCE="${1:?Usage: ./build-deck.sh <notes-file>}"
DECK="slides.md"
OUTPUT_DIR="./dist"

mkdir -p "$OUTPUT_DIR"

echo "[1/4] Structuring content into slides..."
claude -p "
Read $SOURCE. Create a Marp-formatted presentation in $DECK.
Follow all rules in CLAUDE.md under 'Presentation Style Guidelines'.
Include speaker notes for every slide.
"

echo "[2/4] Rendering to all formats..."
marp "$DECK" -o "$OUTPUT_DIR/slides.html" &
marp "$DECK" -o "$OUTPUT_DIR/slides.pdf" &
marp "$DECK" -o "$OUTPUT_DIR/slides.pptx" &
wait

echo "[3/4] Committing to git..."
git add "$DECK"
git commit -m "Generate deck from $(basename "$SOURCE")"

echo "[4/4] Done. Outputs:"
echo "  $DECK                      -- source (editable)"
echo "  $OUTPUT_DIR/slides.html    -- browser preview"
echo "  $OUTPUT_DIR/slides.pdf     -- for distribution"
echo "  $OUTPUT_DIR/slides.pptx    -- for PowerPoint users"
echo ""
echo "To start live editing:"
echo "  marp $DECK -o $OUTPUT_DIR/slides.html --watch"

Run it:

chmod +x build-deck.sh
./build-deck.sh raw-notes.md

From raw notes to a rendered deck in three formats, committed to git. Under 30 seconds. That is not an exaggeration -- the bottleneck is the AI call, and even that finishes before your coffee gets cold.

Why This Beats the GUI Workflow

Picture two parallel universes.

In Universe A, you open PowerPoint. Create slides manually. Fight with formatting for an hour. Save deck_v1.pptx. Email it to your co-presenter. Receive deck_v1_edits.pptx. Merge changes by hand, hoping you catch every edit. Lose track of which version is "the real one."

In Universe B, you write Markdown. An AI agent handles structure and speaker notes. One command renders to any format. Git tracks every change. Branches handle different audiences. Diffs show exactly what changed. Pull requests replace email attachments.

The differences compound over time.

The largest win is speaker notes. Most presenters skip them because writing notes is tedious -- like writing documentation, everyone agrees it matters and nobody wants to do it. With Claude Code generating notes that include timing, transitions, audience-awareness cues, and fallback plans for running long, even a first-time presenter has coaching built into every slide.

The Multi-Pane Setup

The ideal editing setup uses three panes, each with a single responsibility. Left pane: your text editor with slides.md. Top-right pane: Claude Code for structural edits and speaker note generation. Bottom-right pane: marp --watch with the browser showing live output.

You edit content on the left. You ask Claude Code to restructure sections or sharpen notes on the top right. You see the rendered result update in real time on the bottom right. Three panes, one workflow, zero context switching between applications. It is like having a writing partner and a design preview sitting next to you, both updating the moment you finish a thought.

When reviewing a completed deck, two panes suffice: the Markdown source on the left, the rendered HTML on the right. Scroll through both simultaneously. You will catch formatting issues that only appear in the rendered output -- a code block that overflows, a slide with too many bullets, a title that wraps awkwardly.

Recap

Presentations are documents. Documents belong in version control. The content-structuring and speaker-note-writing tasks are exactly what AI agents handle well: mechanical transformation of ideas into structured formats, governed by explicit rules. Humans are bad at this not because it is hard, but because it is boring. Agents do not get bored.

The stack is simple. Marp CLI renders Markdown to slides. Claude Code structures content and writes speaker notes. Git tracks everything. A reusable skill file means future presentations need nothing more than a raw notes file and a single command.

Stop fighting with slide layout tools. Write Markdown. Let the terminal handle the rest.