Marp Presentation

Marp Presentation Workflow

Complete workflow for creating, building, reviewing, and theming Marp Markdown presentations.

When to Use

• "Create a presentation about X"
• "Make slides from this codebase"
• "Export my deck to PDF/PPTX"
• "Review my slides"
• "Theme my presentation" / "Custom colors for my deck"
• "Marp deck from repo"

Capability 1: Create Deck

Generate a complete Marp Markdown presentation from a topic, outline, or codebase analysis.

Modes

Codebase-Driven Mode

When the user wants slides about their project:

1. Analyze the repository — read README, config files, identify tech stack and architecture
2. Propose angles — suggest 2–3 presentation framings:
   • Architecture overview (components, data flow)
   • Onboarding guide (setup, structure, workflow)
   • Technical deep dive (specific module or algorithm)
   • Demo walkthrough (features, user journey)
   • Decision review (trade-offs, alternatives considered)
3. Generate the deck per the rules below

Topic/Outline Mode

When the user provides a topic or bullet points:

1. Clarify scope — if broad, ask about audience and depth
2. Structure narrative — opening hook → core (3–5 sections) → summary/CTA
3. Generate the deck

Frontmatter Template

---
marp: true
theme: default
paginate: true
header: ""
footer: ""
---

Theme options: default (general), gaia (bold keynote), uncover (minimal).

Slide Structure Rules

Content Quality Rules

• One idea per slide — two topics = two slides
• 6×6 guideline — max 6 bullets, max 6 words per bullet
• Progressive disclosure — build complexity gradually
• Mix layouts — alternate text, code, images, split slides
• Speaker notes — <!-- Speaker note text --> after content
• Headings required — every slide gets an h1 or h2

Technical Deck Patterns

<!-- _class: lead -->
# Architecture Overview
How the system fits together

---

## System Components

```mermaid
graph LR
  A[Client] --> B[API Gateway]
  B --> C[Service A]
  B --> D[Service B]
  C --> E[(Database)]

Key Module: Auth

// src/auth/middleware.ts — actual code from repo
export function authenticate(req, res, next) {
  const token = req.headers.authorization;
  // ...
}

### Output

Save to `presentation.md` (or user-specified path). Inform the user they can preview with `marp -s .` or the VS Code Marp extension.

---

## Capability 2: Build Deck

Convert a Marp Markdown file to HTML, PDF, PPTX, or image format.

### Output Formats

| Format | Flag | Best For |
| ------ | ---- | -------- |
| HTML | (default) | Web sharing, live presentations |
| PDF | `--pdf` | Printing, email attachments |
| PPTX | `--pptx` | Corporate sharing, editing in PowerPoint |
| PNG | `--images png` | Social media, thumbnails |

### Build Commands

```bash
# PDF (most universal)
marp slides.md -o slides.pdf --pdf-notes --pdf-outlines --allow-local-files

# PPTX
marp slides.md -o slides.pptx --allow-local-files

# HTML
marp slides.md -o slides.html --allow-local-files

# With custom theme
marp slides.md -o slides.pdf --theme ./custom-theme.css

# Watch mode (live preview)
marp -w slides.md

# Server mode (browser preview)
marp -s .

# Batch conversion
marp -I ./slides/ --pdf

Important Flags

• --allow-local-files — required if deck references local images
• --pdf-notes — includes presenter notes in PDF
• --pdf-outlines — adds bookmarks to PDF

CLI Availability Check

marp --version
# If not found: npx @marp-team/marp-cli@latest --version

Common Errors

Capability 3: Review Deck

Evaluate an existing Marp deck across 6 quality dimensions.

Evaluation Dimensions

1. Structure & Flow

• Clear narrative arc (intro → body → conclusion)?
• Title slide, agenda, and summary/closing present?
• Sections logically grouped?
• Appropriate slide count (1–2 min per slide)?

2. Content Quality

• One main idea per slide?
• Bullets concise (no full sentences)?
• No walls of text (max 6–8 lines)?
• Consistent heading hierarchy?

3. Marp Syntax

• marp: true in frontmatter?
• Valid YAML frontmatter?
• Slide separators (---) with blank lines above/below?
• Correct directive syntax (<!-- _class: lead -->)?
• Code blocks have language specifiers?

4. Visual Variety

• Mix of slide types (text, code, image, split)?
• Not all bullet lists?
• Background images or split layouts used?
• Classes vary appearance (lead, invert)?

5. Accessibility

• Sufficient text contrast?
• Alt text on images?
• Color not sole information carrier?
• Tables have headers?

6. Speaker Notes

• Key slides have notes?
• Notes add talking points (not repeat slide content)?
• Pagination enabled?

Review Output Format

## Deck Review: <filename>

### Summary
<1–2 sentence assessment>

### Score: X/10

### ✅ Strengths
- <what works well>

### ⚠️ Issues Found
#### Structure & Flow
- **Slide N**: <issue and fix>

#### Content Quality
- **Slide N**: <issue and fix>

### 💡 Suggestions
1. <actionable improvement>

After review, offer to apply fixes automatically.

Capability 4: Theme Customization

Built-in Themes

Apply via frontmatter: theme: gaia

Useful classes: <!-- _class: lead --> (centered), <!-- _class: invert --> (dark mode)

Quick Style Override (No Theme File)

---
marp: true
theme: default
style: |
  section {
    background-color: #1a1a2e;
    color: #eaeaea;
    font-family: 'Segoe UI', sans-serif;
  }
  h1, h2 { color: #0078d4; }
  code { background: #2d2d2d; color: #d4d4d4; }
---

Custom Theme File

For full control, create a CSS file (e.g., theme-brand.css):

/* @theme brand-theme */
@import 'default';

:root {
  --primary: #0078d4;
  --bg: #ffffff;
  --fg: #333333;
}

section {
  background-color: var(--bg);
  color: var(--fg);
  font-family: 'Segoe UI', sans-serif;
  padding: 40px;
}

h1 { color: var(--primary); font-size: 2.2em; }
h2 { color: var(--primary); font-size: 1.6em; }

/* Lead slide — centered */
section.lead {
  display: flex;
  flex-direction: column;
  justify-content: center;
  text-align: center;
}

/* Invert class — dark background */
section.invert {
  background-color: #1a1a2e;
  color: #eaeaea;
}

Use with: marp slides.md --theme ./theme-brand.css --pdf

Theme Design Process

1. Gather requirements — primary color, light/dark, font preference, special slide types
2. Generate CSS — base on @import 'default', override custom properties
3. Test — build one slide with each class to verify rendering
4. Document — list available classes and their visual effect

Workflow Integration

Comparison with Other Presentation Skills