Marp — Markdown Presentations

Marp — Markdown Presentation Ecosystem

Create slide decks from plain Markdown. Export to HTML, PDF, PPTX, or images via CLI.

Quick Start

# Verify installed
marp --version
Convert to HTML (default)
marp slides.md -o slides.html
Convert to PDF (requires Chrome/Edge installed)
marp slides.md --pdf -o slides.pdf
Convert to PowerPoint
marp slides.md --pptx -o slides.pptx
Convert to PNG (one image per slide)
marp slides.md --images png
Watch mode (auto-rebuild on save)
marp -w slides.md
Serve with live preview
marp -s ./slides-dir

Slide Syntax

Slides are separated by --- horizontal rulers. Front-matter sets global directives.

---
marp: true
theme: default
paginate: true
Title Slide
Subtitle text here
Second Slide
Bullet points
Work normally
Standard markdown
Third Slide
Code blocks, tables, images — all standard markdown.

Key rule: marp: true in front-matter is required for Marp CLI to process the file.

Directives Reference

Global (whole deck)

| Directive | Values | Purpose | |-----------|--------|---------| | theme | default, gaia, uncover | Built-in themes | | paginate | true/false | Page numbers | | size | 16:9 (default), 4:3 | Slide aspect ratio | | style | CSS string | Custom styles for whole deck | | headingDivider | 1-6 or array | Auto-split slides at headings |

Local (per slide, in HTML comments)

   ← underscore prefix = this slide only (spot directive)

| Directive | Purpose | |-----------|---------| | backgroundColor | Slide background color | | backgroundImage | Background image URL | | color | Text color | | class | CSS class (persists to following slides) | | _class | CSS class (this slide only) | | header | Header text | | footer | Footer text | | paginate | true/false/hold/skip |

Built-in Themes

default

gaia

      ← centered title layout
       ← alternate color scheme
 ← dark centered

uncover

Common to all themes

  ← dark mode variant
      ← traditional aspect ratio (default is 16:9)

Image Syntax (Extended)

Marp extends standard markdown image syntax with keywords in alt text.

Inline images

!w:200              
!h:150              
!w:200 h:150       
!blur:3px           
!grayscale          

Background images

!bg                 
!bg contain        
!bg cover          
!bg fit            
!bg 50%            
!bg right          
!bg left:40%       

Multiple backgrounds

!bg
!bg
!bg

Split backgrounds (content + image)

!bg right:60%
Architecture
Component A talks to B
B stores in database
C reads from cache

Custom CSS

Inline in front-matter

---
marp: true
theme: default
style: |
  section {
    font-family: 'Inter', sans-serif;
  }
  section.brand {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    color: white;
  }
  h1 { color: #2d3748; }
  img[alt~="center"] {
    display: block;
    margin: 0 auto;
  }

Using custom classes

Branded Slide
This slide uses the custom brand class defined in the style block.

Custom theme file

# Create theme CSS file, then use with --theme flag
marp slides.md --theme ./custom-theme.css --pdf

Diagrams in Slides

Marp doesn't natively render Mermaid. Two approaches:

Approach 1: Pre-render to SVG (recommended)

# Install mermaid CLI
npm install -g @mermaid-js/mermaid-cli
Render .mmd files to SVG
mmdc -i diagram.mmd -o diagram.svg
Reference in slides
!bg right:50%

Approach 2: HTML embed with mermaid.js

---
marp: true

graph LR
    A[User] --> B[Flash App]
    B --> C[API]
    C --> D[Database]

> Note: HTML embed only works in HTML output, not PDF/PPTX. Use pre-rendered SVGs for PDF export.

Presenter Notes

Add notes below --- comment blocks — visible in presenter view, hidden in slides.

## Slide Title
Content here

CLI Reference

# Basic conversion
marp input.md                     # → input.html
marp input.md -o output.pdf       # → PDF
marp input.md --pptx              # → PPTX
marp input.md --images png        # → PNG per slide
Options
marp --pdf --allow-local-files slides.md   # Allow local image paths in PDF
marp --html slides.md                       # Enable HTML tags in markdown
marp --theme ./theme.css slides.md          # Custom theme
marp --title "My Deck" slides.md            # Set HTML title
Batch conversion
marp ./slides-dir/                 # Convert all .md in directory
Server + watch
marp -s ./slides-dir              # HTTP server with live reload
marp -w slides.md                 # Watch and rebuild on change
Configuration file (marp.config.mjs)
Place in project root — auto-detected by CLI

marp.config.mjs example

export default {
  allowLocalFiles: true,
  html: true,
  themeSet: './themes',
  output: './output',
};

Patterns for Product Docs

Requirement doc template

---
marp: true
theme: default
paginate: true
header: "Flash — Product Spec"
footer: "Confidential"
style: |
  section { font-size: 24px; }
  section.cover { text-align: center; }
  section.cover h1 { font-size: 48px; }
Feature: Cashu Flashcards
Version: 1.0 · Date: 2026-03-19 · Author: Product Team
Overview
Brief description of what this feature does and why.
User Flow
!bg right:55% contain
1. User opens Flashcard tab
2. Selects amount
3. Confirms creation
4. Receives Cashu token
Architecture
!bg contain
Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| R1 | Create flashcard from USD wallet | P0 |
| R2 | Redeem flashcard to any Flash user | P0 |
| R3 | Expire after 30 days | P1 |
Open Questions
[ ] Max flashcard value?
[ ] Offline redemption support?

Common Mistakes

| Mistake | Fix | |---------|-----| | Forgot marp: true | Add to front-matter — CLI ignores file without it | | PDF export fails | Needs Chrome/Chromium/Edge installed. Use --allow-local-files for local images | | Mermaid not rendering | Pre-render to SVG with mmdc, embed as image | | Background image not showing | Use !bg — the bg keyword is required | | Styles not applying | Check CSS selector — slides are

# Verify installed
marp --version
Convert to HTML (default)
marp slides.md -o slides.html
Convert to PDF (requires Chrome/Edge installed)
marp slides.md --pdf -o slides.pdf
Convert to PowerPoint
marp slides.md --pptx -o slides.pptx
Convert to PNG (one image per slide)
marp slides.md --images png
Watch mode (auto-rebuild on save)
marp -w slides.md
Serve with live preview
marp -s ./slides-dir