Marp Presentations: Markdown Becomes Slides

December 10, 2025 · 12 min read

#marp #presentations #markdown #markdown-et-al

Marp Presentations

Marp turns Markdown into presentation slides. Write text, get a deck. No clicking through ribbons. No pixel-perfect alignment battles. No “the font changed when I opened it on another computer.”

Why Marp Matters

Presentations as code - Version control, PR reviews, collaborative editing
Markdown-based - If you know Markdown, you already know Marp
Consistent styling - Themes handle design, you handle content
No binary files - Git diffs show actual changes
Fast iteration - Edit text, reload, done
LLM-native - AI generates presentation content fluently

Markdown + Marp: Slides Are Just Markdown

Marp is Markdown with slide delimiters. That’s it.

A simple deck:

---
marp: true
---

# First Slide

Content here.

---

# Second Slide

More content.

The --- creates slide breaks. Everything else is standard Markdown: headers, lists, code blocks, images, links.

Why this connection matters:

One format for docs, diagrams, and presentations
Skills transfer: learn Markdown once, use everywhere
Embed Mermaid diagrams in Marp slides
Mix text, code, and visuals seamlessly

The trilogy complete:

Markdown - Structure your content
Mermaid - Visualize your ideas
Marp - Present your work

All plain text. All version-controllable. All LLM-friendly.

LLMs and Marp: Presentation Generation

LLMs generate Marp presentations naturally because it’s Markdown they already understand.

The workflow:

You: "Create a Marp presentation about API design with 5 slides"
LLM: [Generates complete Marp Markdown]
You: "Add a slide about error handling with code examples"
LLM: [Inserts new slide with proper formatting]

Why it works:

Marp syntax is Markdown + frontmatter directives
Models trained on billions of Markdown documents
Clear structure: frontmatter → slides → content
No visual ambiguity - text is explicit

Prompt tips:

“Create a Marp presentation with…”
“Use the default theme with…”
Specify slide count: “5 slides covering…”
Request specific elements: “Include code examples and a Mermaid diagram”

Iteration is easy:

Ask for content changes: “Make slide 3 more concise”
Request structural changes: “Split slide 2 into two slides”
Style adjustments: “Add background color to the title slide”

No uploading PDFs. No describing layouts. Just text edits.

Core Syntax

Frontmatter

Every Marp deck starts with YAML frontmatter:

---
marp: true
theme: default
paginate: true
backgroundColor: #fff
---

Key directives:

marp: true - Enable Marp processing
theme: - Choose theme (default, gaia, uncover)
paginate: - Show slide numbers
backgroundColor: - Background color
color: - Text color
size: - Slide size (16:9, 4:3)

Slide Breaks

--- → Horizontal rule creates new slide

# Slide 1

Content

---

# Slide 2

More content

Headers and Content

# Header → Large title slide ## Subheader → Content slide with header

All standard Markdown works:

Bold, italic, ~~strikethrough~~
Lists (ordered and unordered)
Code blocks with syntax highlighting
Links and images
Blockquotes
Tables

Scoped Directives

Apply styling to specific slides using  comments:

<!-- backgroundColor: #1e1e1e -->
<!-- color: #fff -->

# Dark Slide

This slide has custom colors.

---

# Back to Default

Regular styling resumes.

Images

Full width:

![](image.jpg)

Background image:

![bg](background.jpg)

Background with options:

![bg left](image.jpg)
![bg right:40%](image.jpg)
![bg fit](image.jpg)
![bg contain](image.jpg)

Layouts

Two columns using background images:

![bg left:40%](diagram.png)

# Content

Text appears on the right side.

Split content:

Left column content

Right column content

Speaker Notes

Hidden notes for presenter (not shown on slides):

# My Slide

Visible content here.

<!--
Speaker notes here.
These are only visible in presenter mode.
-->

Built-in Themes

Default - Clean, professional Gaia - Colorful, modern Uncover - Minimalist, animated

Select in frontmatter:

---
marp: true
theme: gaia
---

Common Patterns

Title Slide

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

# Presentation Title
## Subtitle or Tagline

**Your Name**
Date

Code Examples

# Code Example

```javascript
async function fetchData() {
  const response = await fetch('/api/data');
  return response.json();
}
```

- Syntax highlighting included
- Multiple languages supported

Lists with Fragments

Show list items progressively (not standard Marp, but can be done with HTML):

# Key Points

* First point
* Second point
* Third point

Mermaid Integration

Embed diagrams in slides:

# System Architecture

```mermaid
graph LR
    Client --> API
    API --> Database
```

Quote Slides

# Inspiration

> "Software is disposable. Knowledge isn't."
>
> — Your Name

Advanced Features

Custom Themes

Create CSS themes:

/* custom-theme.css */
section {
  background: #1e1e1e;
  color: #fff;
  font-family: 'Helvetica', sans-serif;
}

h1 {
  color: #61dafb;
}

Use in frontmatter:

---
marp: true
theme: custom-theme
---

Math Equations

Marp supports KaTeX for math:

# Math Example

Inline: $E = mc^2$

Block:
$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Auto-scaling

Marp automatically scales text to fit slides. Force fitting with:

<!-- fit -->
# This Header Will Auto-Scale to Fit

Class Directives

Apply custom CSS classes:

<!-- class: lead -->

# Centered Content

This slide uses the "lead" class.

Common Pitfalls

Frontmatter required - Must start with marp: true
Slide breaks - Three dashes --- not two or four
Image paths - Relative to Markdown file location
HTML in Markdown - Works but may break in some renderers
Theme availability - Custom themes need CSS files
Export formats - PDF export may require specific tools

Tools

CLI:

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

# Convert to HTML
marp slides.md -o slides.html

# Convert to PDF
marp slides.md -o slides.pdf

# Watch mode
marp -w slides.md

VSCode Extension:

“Marp for VS Code” - Live preview, export, theme support

Online Editor:

Marp Web - Browser-based editor and preview

Export Formats:

HTML (interactive, self-contained)
PDF (print-ready)
PPTX (PowerPoint, via Pandoc)

Hosting:

GitHub Pages - Host HTML output
Netlify/Vercel - Deploy from repo
Any static host - It’s just HTML

The Philosophy

Presentations should be:

Reviewable - See changes in Git diffs
Collaborative - Multiple authors in PRs
Reusable - Copy slides between decks as text
Searchable - Grep through presentation content
Archivable - Text files don’t rot

Marp delivers all of this. PowerPoint delivers none of it.

“Can you send me slide 7?” → Send 10 lines of Markdown.

“Let’s merge our decks.” → Copy-paste text.

“What changed since last version?” → Git diff.

See It In Action

Here are complete presentation examples showing raw Marp and what they create:

Example 1: Technical Talk with Code

Raw:

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

# API Design Best Practices
## Building Robust REST APIs

**Jane Doe**
December 2025

---

## Agenda

1. RESTful Principles
2. Error Handling
3. Authentication
4. Rate Limiting

---

## RESTful Principles

- **Resources** - Use nouns, not verbs
  - ✅ `GET /users/123`
  - ❌ `GET /getUser/123`
- **HTTP Methods** - Leverage verbs correctly
  - `GET` - Read
  - `POST` - Create
  - `PUT/PATCH` - Update
  - `DELETE` - Delete

---

## Error Handling

```javascript
// Good: Consistent error structure
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 123 not found",
    "details": {}
  }
}

// Bad: Inconsistent structure
{
  "err": "not found"
}
```

---

## Authentication Flow

```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>Database: Validate
    Database-->>API: Success
    API-->>Client: JWT Token
    Client->>API: GET /data + Token
    API-->>Client: Protected Data
```

---

<!-- backgroundColor: #1e1e1e -->
<!-- color: #fff -->

## Key Takeaways

- Design for consistency
- Always return proper status codes
- Document your API (OpenAPI/Swagger)
- Version your endpoints (`/v1/`, `/v2/`)

---

# Questions?

**Contact:** jane@example.com
**Slides:** github.com/jane/api-talk

Creates: A 7-slide technical presentation with code examples, Mermaid diagram, custom styling on one slide, and clear structure.

Example 2: Product Pitch Deck

Raw:

---
marp: true
theme: gaia
paginate: true
backgroundColor: #fff
---

<!-- class: lead -->

# DevTools Pro
## Ship Faster. Debug Smarter.

---

## The Problem

Developers spend **40% of their time** debugging.

- Unclear error messages
- Missing context
- Poor logging
- Difficult reproduction

**What if debugging was instant?**

---

## Our Solution

![bg right:40%](product-screenshot.png)

**DevTools Pro** provides:

- 🔍 Intelligent error tracking
- 📊 Performance monitoring
- 🔗 Automatic context capture
- ⚡ Real-time alerts

---

## How It Works

```mermaid
graph LR
    App[Your App] --> SDK[DevTools SDK]
    SDK --> Cloud[Cloud Platform]
    Cloud --> Dashboard[Web Dashboard]
    Cloud --> Alerts[Slack/Email]
```

1. Install SDK (5 minutes)
2. Errors auto-captured
3. Get notified instantly

---

## Pricing

| Plan | Price | Features |
|------|-------|----------|
| **Free** | $0 | 1k errors/month |
| **Pro** | $49 | 50k errors/month |
| **Team** | $199 | Unlimited + SSO |

**14-day free trial. No credit card.**

---

<!-- backgroundColor: #667eea -->
<!-- color: #fff -->

# Try DevTools Pro Today

**www.devtools.pro**

Start shipping with confidence.

Creates: A 6-slide product pitch with problem/solution structure, visual diagrams, pricing table, and call-to-action with custom branding colors.

Example 3: Educational Workshop

Raw:

---
marp: true
theme: uncover
paginate: true
---

# Git Workflows
## Mastering Branch Strategies

---

## What We'll Cover

1. Feature Branch Workflow
2. Git Flow
3. Trunk-Based Development
4. Choosing the Right Strategy

<!--
Speaker notes: Start with quick poll - who uses Git daily?
Adjust depth based on audience experience.
-->

---

## Feature Branch Workflow

```mermaid
gitGraph
    commit
    branch feature-login
    checkout feature-login
    commit
    commit
    checkout main
    merge feature-login
    commit
```

**Process:**
1. Create branch from `main`
2. Develop feature
3. Open Pull Request
4. Review + Merge

---

## When to Use Each Strategy

| Strategy | Team Size | Release Frequency | Complexity |
|----------|-----------|-------------------|------------|
| Feature Branch | Small-Medium | Weekly | Low |
| Git Flow | Medium-Large | Scheduled | High |
| Trunk-Based | Any | Continuous | Medium |

**Key:** Match workflow to your team's needs, not trends.

---

## Best Practices

- ✅ Small, focused commits
- ✅ Descriptive commit messages
- ✅ Frequent rebasing
- ✅ Protected main branch
- ❌ Long-lived feature branches
- ❌ "WIP" commits in history

---

## Exercise Time!

**Scenario:** Your team needs to deploy a hotfix while 3 features are in development.

👥 **Group Discussion (10 min):**
- How do you handle this with your current workflow?
- What challenges arise?
- How would Git Flow handle it differently?

<!--
Speaker notes: Walk around, facilitate discussions.
Prepare to share common patterns from other teams.
-->

---

<!-- fit -->

# Questions & Resources

**Workshop Materials:** github.com/workshop/git-workflows
**Cheat Sheet:** git-workflow-guide.pdf
**Next Session:** Advanced Git - Rebasing & Cherry-picking

Creates: A 7-slide workshop presentation with interactive elements, discussion prompts, speaker notes, and educational content including diagrams, tables, and exercises.

Example 4: Company All-Hands

Raw:

---
marp: true
theme: default
backgroundColor: #f8f9fa
paginate: true
---

![bg left:30%](company-logo.png)

# Q4 2025 Review
## All-Hands Meeting

December 10, 2025

---

## Agenda

1. **Product Updates** - What we shipped
2. **Metrics** - Growth & engagement
3. **Team Highlights** - Celebrating wins
4. **Q1 2026 Goals** - What's next

---

## Product Shipped This Quarter

- ✅ Mobile app redesign (Oct 15)
- ✅ API v2 launch (Nov 1)
- ✅ Enterprise SSO (Nov 20)
- ✅ Advanced analytics (Dec 5)

**Impact:** 40% increase in mobile engagement

---

## Growth Metrics

| Metric | Q3 | Q4 | Change |
|--------|--------|--------|--------|
| **Users** | 50k | 85k | +70% 📈 |
| **Revenue** | $200k | $340k | +70% 📈 |
| **NPS** | 45 | 62 | +17pts 📈 |
| **Churn** | 8% | 5% | -3pts 📉 |

**Trend:** All key metrics moving in right direction

---

## Team Highlights

**Engineering**
- Reduced deploy time from 30min to 5min
- Zero critical incidents this quarter

**Design**
- Won "Best Mobile UX" award
- 95% positive user feedback on redesign

**Sales**
- Closed 3 enterprise deals ($500k ARR)
- Expanded to EMEA region

---

<!-- backgroundColor: #667eea -->
<!-- color: #fff -->

## Q1 2026 Goals

1. Launch AI-powered recommendations
2. Reach 100k users
3. Achieve SOC 2 certification
4. Open NYC office

**Theme:** Scale with Quality

---

## Thank You

Questions?

**Slides:** company.internal/all-hands-q4-2025
**Feedback:** #all-hands-feedback

---

<!-- backgroundColor: #f8f9fa -->

![bg right:40%](team-photo.jpg)

# See You Next Quarter!

Keep building great things.

Creates: An 8-slide all-hands presentation with metrics, team updates, mixed layouts, custom colors, and images - professional internal communication format.

Quick Reference

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

# Slide Title

Content here.

---

## Next Slide

- Bullet points
- Code blocks
- Images: ![](image.jpg)
- Background: ![bg](bg.jpg)

---

<!-- backgroundColor: #1e1e1e -->
<!-- color: #fff -->

# Custom Styling

Export:

marp slides.md -o slides.html
marp slides.md -o slides.pdf

That’s presentations. As code.

Previous: Mermaid Diagrams

Series complete: Markdown → Mermaid → Marp. The plain text trilogy.

Part of the VSCode Content Creator workflow.

Back to Blog

Posts

Marp Presentations: Markdown Becomes Slides

Marp Presentations

Why Marp Matters

Markdown + Marp: Slides Are Just Markdown

LLMs and Marp: Presentation Generation

Core Syntax

Frontmatter

Slide Breaks

Headers and Content

Scoped Directives

Images

Layouts

Speaker Notes

Built-in Themes

Common Patterns

Title Slide

Code Examples

Lists with Fragments

Mermaid Integration

Quote Slides

Advanced Features

Custom Themes

Math Equations

Auto-scaling

Class Directives

Common Pitfalls

Tools

The Philosophy

See It In Action

Example 1: Technical Talk with Code

Example 2: Product Pitch Deck

Example 3: Educational Workshop

Example 4: Company All-Hands

Quick Reference

Posts