Marp — Markdown Presentation Ecosystem

Marp converts Markdown into professional HTML, PDF, PPTX, and image slides via Marp CLI. No proprietary formats, no GUI.

When to Activate

"create a presentation", "make slides", "build a deck", "pitch deck"
"convert markdown to slides", "markdown to PDF"
"speaker notes", "presenter notes in slides"
"set up Marp", "Marp theme", "Marp project"
Any task where the output is a .pptx, .pdf, or HTML slide deck

Workflow

Step 1 — Ensure Marp CLI Is Installed

which marp || npx @marp-team/marp-cli@latest --version

If not present, install it:

npm install --save-dev @marp-team/marp-cli   # project
npm install -g @marp-team/marp-cli           # global

Or run via npx (no install required):

npx @marp-team/marp-cli@latest [command]

Step 2 — Create or Review the Markdown Source

Create slides.md (or any .md file). Key conventions:

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

# Slide 1 Title

Content here.

---

# Slide 2 Title

- Bullet point
- Another point

<!-- speaker notes: only visible in presenter mode -->

---

## Even-Level Headings Start New Slides (H2 = new slide)
### H3 is a Section Label (no slide break)

Core Front Matter Options

---
marp: true              # enable Marp processing
theme: default          # built-in: default, gaia, uncover
paginate: true          # show page numbers
backgroundColor: #1e1e1e # dark background
header: "Title"         # persistent header
footer: "© 2026"        # persistent footer
---

# Or override per-slide with directives:
<!-- _color: white -->
<!-- _backgroundColor: #000 -->
<!-- _class: lead -->

Slide Separators

Syntax	Effect
`---` on its own line	Hard slide break
`--` on its own line	Soft break (same section)
`<!-- fit -->`	Auto-fit text to slide

Speaker Notes

<!-- speaker notes:
This is hidden in slides but shown in presenter mode.
- Sub-points work too.
-->

Charts & Code (Marp Core Features)

```chart
type: bar
data:
  labels: [Q1, Q2, Q3, Q4]
  datasets:
    - label: Revenue
      data: [12, 19, 15, 28]
```
{type=bar}
```

Step 3 — Choose Output Format & Run

# HTML (default, opens in browser)
marp slides.md

# PDF (requires Chrome/Edge/Firefox)
marp slides.md --pdf

# PowerPoint
marp slides.md --pptx

# PNG images (one per slide)
marp slides.md --images png

# JPEG images
marp slides.md --images jpeg

# Output to specific path
marp slides.md -o dist/slides.html

# Watch mode (auto-reconvert on save)
marp slides.md -w

# HTTP server (on-demand conversion, ?pdf, ?pptx, ?png in query string)
marp slides.md -s
PORT=8080 marp slides.md -s

# Preview window (desktop only)
marp slides.md -p

# Batch: entire directory
marp --input-dir ./slides/ -o ./dist/

Useful Flags

--pdf-notes           # include speaker notes in PDF
--pdf-outlines        # add PDF bookmarks
--pptx-editable       # editable PPTX (requires LibreOffice)
--image-scale 2       # scale factor for image export
--allow-local-files   # embed local images (HTML only)
--browser chrome      # force specific browser for PDF/image export

Step 4 — Verify Output

HTML: open the .html file in a browser, test keyboard navigation (arrows, Space)
PDF: open and check pagination, fonts, image quality
PPTX: open in PowerPoint/Keynote/Google Slides
Images: check resolution, especially for --image-scale 2

Step 5 — Automation (Optional)

For CI/CD or project integration:

// package.json scripts
{
  "scripts": {
    "slides:html": "marp src/slides.md -o public/slides.html",
    "slides:pdf": "marp src/slides.md --pdf",
    "slides:watch": "marp src/slides.md -w"
  }
}

Or use the --server mode to serve presentations from a docs site:

PORT=4321 marp docs/slides/ -s
# Access at http://localhost:4321/slides.md?pdf

Marp Core Built-in Themes

Theme	Best For
`default`	Clean, minimal, all-purpose
`gaia`	Modern with a sidebar, section headers
`uncover`	Full-bleed image backgrounds
Custom theme	CSS custom properties — see `marp-core` docs

Customizing Themes

Override via style block or custom CSS:

---
marp: true
style: |
  section {
    background: #0d1117;
    color: #e6edf3;
    font-family: 'Inter', sans-serif;
  }
  h1 { color: #58a6ff; }
  footer { color: #8b949e; }
---

Project Structure Recommendation

project/
├── slides/
│   ├── cover.md        # Title slide
│   ├── agenda.md       # Overview
│   ├── content-1.md   # Section 1
│   ├── content-2.md   # Section 2
│   └── qa.md          # Closing slide
├── src/
│   └── presentation.md  # Combined deck (use !include directives)
├── public/
│   └── presentation.html
└── dist/
    ├── presentation.pdf
    └── presentation.pptx

Combine multiple files:

<!-- $slide: cover.md -->
<!-- $slide: agenda.md -->
<!-- !include slides/content-1.md -->

Troubleshooting

Problem	Fix
"marp: command not found"	Use `npx @marp-team/marp-cli@latest` or install globally
PDF export fails	Install Chrome/Edge/Firefox; use `--browser chrome`
Images not found	Use absolute paths or `--allow-local-files` for HTML
PPTX not editable	Re-export with `--pptx-editable` (requires LibreOffice)
Fonts look wrong	Bundle fonts or use web-safe fonts in CSS
Server mode 404	Ensure `index.md` or `slides.md` exists in served dir

Key Marpit/Marp Markdown Extensions

Extension	Example
Directives (global)	`<!-- theme: gaia -->`
Directives (per-slide)	`<!-- _class: lead -->`
Built-in filters	`<!-- fit -->`, `<!-- _color: red -->`
Code blocks	Fenced code with language and Marp extensions
Charts (core)	```chart blocks
Math	```math blocks via KaTeX

marp

Files1

SKILL.mdskills/marp/SKILL.md