Marp Presentation Skill

Create professional slide presentations using Markdown with Marp (Markdown Presentation Ecosystem). This skill covers everything from basic slides to advanced theming and multi-format export.

When to Use This Skill

USE When

• Creating presentations from Markdown content
• Need quick slide creation without design overhead
• Want version-controlled presentations (Git-friendly)
• Require multiple output formats (PDF, HTML, PPTX)
• Building automated presentation pipelines
• Need consistent branding across presentations
• Creating technical presentations with code
• Need math equations in slides

DON'T USE When

• Need complex animations and transitions (use PowerPoint/Keynote)
• Require real-time collaboration (use Google Slides)
• Building interactive web applications (use reveal.js directly)
• Need embedded videos with playback controls
• Building documentation websites (use MkDocs or Docusaurus)

Prerequisites

Installation

# Using npm (recommended)
npm install -g @marp-team/marp-cli

# Using npx (no installation needed)
npx @marp-team/marp-cli --version

# Using Homebrew (macOS)
brew install marp-cli

# Using Docker
docker pull marpteam/marp-cli

# Verify installation
marp --version

VS Code Extension

# Install from VS Code marketplace
# Search: "Marp for VS Code"
# Extension ID: marp-team.marp-vscode

code --install-extension marp-team.marp-vscode

Core Capabilities

1. Basic Slide Creation

<!-- slides.md -->
---
marp: true
---

# Welcome to My Presentation

A subtitle for the first slide

---

## Slide 2: Key Points

- First important point
- Second important point
- Third important point

---

## Slide 3: Code Example

```python
def hello(name: str) -> str:
    return f"Hello, {name}!"

---

Thank You!

Questions?

### 2. Frontmatter Configuration

```markdown
---
marp: true
title: Project Presentation
description: Quarterly review for Q4 2025
author: Your Name
theme: default
paginate: true
header: 'Company Name'
footer: 'Confidential - Internal Use Only'
size: 16:9
math: katex
style: |
  section {
    background-color: #fefefe;
  }
---

# First Slide

Content here...

3. Themes and Styling

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

<!-- Available built-in themes: default, gaia, uncover -->

# Default Theme

Clean and professional

---

<!-- Switching themes mid-presentation -->
<!-- _theme: gaia -->

# Gaia Theme

Bold and colorful

---

<!-- Custom background color -->
<!-- _backgroundColor: #1e3a5f -->
<!-- _color: white -->

# Dark Background

With light text

4. Custom CSS Theme

/* themes/custom.css */

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

section {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  font-family: 'Inter', sans-serif;
}

section h1 {
  color: #ffffff;
  font-size: 2.5em;
  text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.3);
}

section h2 {
  color: #e0e7ff;
  border-bottom: 2px solid rgba(255, 255, 255, 0.3);
}

section.lead {
  display: flex;
  flex-direction: column;
  justify-content: center;
  text-align: center;
}

section.invert {
  background: #1f2937;
  color: #f3f4f6;
}

5. Directives and Classes

---
marp: true
---

<!-- Local directive (applies to current slide only) -->
<!-- _class: lead -->
<!-- _backgroundColor: #2563eb -->
<!-- _color: white -->

# Title Slide

Subtitle here

---

<!-- _paginate: false -->
<!-- _header: '' -->

# Clean Slide

No pagination or headers

---

<!-- Scoped styling -->
<style scoped>
h1 { color: #dc2626; }
ul li { font-size: 1.2em; }
</style>

# Scoped Styles

- Custom styling for this slide only

6. Speaker Notes

---
marp: true
---

# Presentation Title

Overview of topics

<!--
Speaker notes go here.

Key points to mention:
1. Welcome the audience
2. Introduce yourself
3. Preview the agenda

Time: ~2 minutes
-->

---

## Code Example

```python
def process_data(data):
    return [x * 2 for x in data]

<!-- Code walkthrough: 1. Explain the function signature 2. Discuss list comprehension Demo: Run this in the terminal -->

### 7. Images and Backgrounds

```markdown
---
marp: true
---

<!-- Full background image -->
![bg](./images/background.jpg)

# Full Background

Text over image

---

<!-- Background with opacity -->
![bg opacity:0.3](./images/photo.jpg)

# Semi-transparent Background

---

<!-- Split layout -->
![bg right:40%](./images/sidebar.png)

# Split Layout

Image on the right side, content on the left

---

<!-- Background with gradient -->
![bg](linear-gradient(to bottom right, #3b82f6, #8b5cf6))

# Gradient Background

---

<!-- Inline images with sizing -->
## Product Features

![width:300px](./images/feature1.png) ![width:300px](./images/feature2.png)

8. Math Equations

---
marp: true
math: katex
---

# Mathematical Equations

## Inline Math

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$

---

## Block Math

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$

9. Mermaid Diagrams

---
marp: true
---

# Diagrams

## Flowchart

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process A]
    B -->|No| D[Process B]
    C --> E[End]
    D --> E

---

Sequence Diagram

sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Request data
    S-->>U: Response

### 10. CLI Usage

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

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

# Convert to PPTX
marp slides.md -o slides.pptx

# Watch mode
marp -w slides.md -o slides.html

# Server mode with live preview
marp -s slides.md

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

# Allow local file access
marp slides.md --allow-local-files -o slides.pdf

# PDF with speaker notes
marp slides.md -o slides.pdf --pdf-notes

11. Configuration File

# .marprc.yml
html: true
allowLocalFiles: true
output: "./dist"
theme: "./themes/corporate.css"

pdf: true
pdfNotes: true

watch: false
server: false
serverPort: 8080

12. VS Code Settings

// .vscode/settings.json
{
  "markdown.marp.enableHtml": true,
  "markdown.marp.themes": [
    "./themes/custom.css"
  ],
  "markdown.marp.mathTypesetting": "katex",
  "markdown.marp.exportType": "pdf"
}

13. GitHub Actions Workflow

# .github/workflows/presentations.yml
name: Build Presentations

on:
  push:
    branches: [main]
    paths: ['presentations/**']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Marp CLI
        run: npm install -g @marp-team/marp-cli

      - name: Build presentations
        run: |
          mkdir -p dist
          for file in presentations/*.md; do
            filename=$(basename "$file" .md)
            marp "$file" --allow-local-files -o "dist/${filename}.pdf"
          done

      - uses: actions/upload-artifact@v4
        with:
          name: presentations
          path: dist/

14. Docker Usage

# Build with Docker
docker run --rm -v $(pwd):/app marpteam/marp-cli \
  /app/slides.md -o /app/slides.pdf

# Run server
docker run --rm -p 8080:8080 -v $(pwd):/app marpteam/marp-cli \
  -s /app/slides.md

15. Advanced Layouts

---
marp: true
---

<style>
.columns { display: grid; grid-template-columns: 1fr 1fr; gap: 2em; }
.centered { display: flex; flex-direction: column; justify-content: center; align-items: center; }
</style>

---

# Two Column Layout

<div class="columns">
<div>

## Left Column

- Point 1
- Point 2

</div>
<div>

## Right Column

![width:400px](./images/diagram.png)

</div>
</div>

Integration Examples

Integration with npm Project

// package.json
{
  "scripts": {
    "start": "marp -s ./slides",
    "watch": "marp -w ./slides -o ./dist",
    "build": "marp ./slides --output ./dist",
    "build:pdf": "marp ./slides -o ./dist --pdf"
  },
  "devDependencies": {
    "@marp-team/marp-cli": "^3.0.0"
  }
}

Integration with Makefile

SLIDES_DIR = slides
OUTPUT_DIR = dist

.PHONY: html pdf clean serve

html:
	marp $(SLIDES_DIR)/*.md --output $(OUTPUT_DIR)

pdf:
	marp $(SLIDES_DIR)/*.md --output $(OUTPUT_DIR) --pdf --allow-local-files

clean:
	rm -rf $(OUTPUT_DIR)

serve:
	marp -s $(SLIDES_DIR)

Best Practices

1. Project Structure

presentations/
├── slides/
│   ├── quarterly-review.md
│   └── product-demo.md
├── themes/
│   └── corporate.css
├── images/
├── dist/
├── .marprc.yml
└── package.json

2. Slide Template

---
marp: true
theme: corporate
paginate: true
header: 'Company | Title'
footer: '2026'
---

<!-- _class: title -->
<!-- _paginate: false -->

# Presentation Title

**Presenter Name** | *Date*

---

# Agenda

1. Topic One
2. Topic Two
3. Q&A

---

<!-- _class: section -->

# Section 1

---

## Content Slide

- Key point
- Another point

---

<!-- _class: title -->

# Thank You

Questions?

3. Image Guidelines

<!-- Use consistent sizing -->
![width:800px](./full-width.png)
![width:400px](./medium.png)

<!-- Use relative paths -->
![](./images/diagram.png)

<!-- Include alt text -->
![Architecture diagram](./images/arch.png)

Troubleshooting

PDF Export Fails

# Specify Chrome path
marp slides.md -o slides.pdf --chrome-path /usr/bin/chromium-browser

# Use Chrome arguments for headless environments
marp slides.md -o slides.pdf \
  --chrome-arg=--no-sandbox \
  --chrome-arg=--disable-setuid-sandbox

Images Not Loading

# Enable local file access
marp slides.md -o slides.pdf --allow-local-files

# Use relative paths from markdown file location
![](./images/photo.png)

Custom Theme Not Applied

# Specify theme file path
marp slides.md --theme ./themes/custom.css -o slides.html

# Ensure theme has correct header comment
# /* @theme custom-theme */

Debug Mode

marp slides.md -o slides.pdf --debug
marp --version

Version History

v1.0.0 (2026-01-17)

• Initial skill creation
• Basic slide creation with Markdown
• Theme customization
• Speaker notes and presenter view
• Image and background handling
• Math equations with KaTeX
• Mermaid diagram integration
• CLI usage and configuration
• VS Code extension setup
• GitHub Actions workflow
• Best practices and troubleshooting

Related Resources

• Marp Official Documentation
• Marp CLI GitHub
• Marp VS Code Extension
• KaTeX Documentation
• Mermaid Diagrams

---

Create professional presentations from Markdown with powerful theming and multi-format export.