| name | marp |
| description | Create and edit slideshows with Marp, the Markdown-based presentation tool. Use when asked to "create a slideshow", "make a presentation", "build a slide deck", "edit slides", "add a slide", "marp presentation", "markdown slides", or when working with .md files that have marp: true in front matter. Supports themes, directives, image syntax, math typesetting, pagination, and export to HTML/PDF/PPTX. |
Marp Slideshow Skill
Create and edit presentation slide decks using Marp (Markdown Presentation Ecosystem). Marp converts Markdown files into HTML, PDF, and PPTX presentations.
When to Use This Skill
- User asks to create a slideshow, presentation, or slide deck
- User wants to edit, add, or modify slides in a Marp file
- User is working with a
.md file containing marp: true in front matter
- User asks about Marp syntax, directives, themes, or image handling
- User wants to export a presentation to PDF, PPTX, or HTML
Basic Slide Structure
Every Marp file must have marp: true in the YAML front matter. Slides are separated by horizontal rulers (---).
---
marp: true
---
# Slide 1
Hello, world!
---
# Slide 2
Marp splits slides by horizontal ruler.
- Marp uses CommonMark Markdown syntax
- Line breaks in a paragraph convert to
<br /> automatically
- The
<style> tag is allowed for tweaking theme CSS
- Most other HTML tags are disabled by default for security
Alternative rulers ___, ***, or - - - also work as slide separators.
Directives
Directives control theme, pagination, headers, footers, and slide styling. Define them in YAML front matter or HTML comments.
Front Matter (Global)
---
marp: true
theme: default
paginate: true
header: 'My Presentation'
footer: '© 2026'
---
HTML Comment (Anywhere)
<!--
theme: default
paginate: true
-->
Global Directives
Settings that apply to the entire slide deck.
| Directive | Description |
|---|
theme | Set theme name (default, gale, uncover) |
style | Specify CSS for tweaking theme |
headingDivider | Auto-split slides at heading level (1-6 or array) |
size | Slide size preset (16:9, 4:3) |
math | Math library: mathjax (default) or katex |
title | Slide deck title |
author | Slide deck author |
description | Slide deck description |
keywords | Comma-separated keywords |
url | Canonical URL (HTML export) |
image | Open Graph image URL (HTML export) |
marp | Enable Marp in VS Code (true/false) |
Local Directives
Settings that apply to the current slide and subsequent slides (inherited).
| Directive | Description |
|---|
paginate | Show page number: true, false, hold, skip |
header | Slide header content |
footer | Slide footer content |
class | HTML class for the slide <section> element |
backgroundColor | Slide background color |
backgroundImage | Slide background image |
backgroundPosition | Background position (default: center) |
backgroundRepeat | Background repeat (default: no-repeat) |
backgroundSize | Background size (default: cover) |
color | Text color |
Directive Inheritance
Local directives inherit to subsequent slides until overridden:
<!-- backgroundColor: lightblue -->
# Page 1 — light blue background
---
# Page 2 — also light blue (inherited)
---
<!-- backgroundColor: white -->
# Page 3 — white background
Scoped Directives (Single Slide Only)
Prefix with _ to apply only to the current slide, without inheriting:
<!-- _backgroundColor: lightblue -->
# This slide only has a light blue background
---
# This slide is back to the default
Built-in Themes
Marp ships with three built-in themes: default, gale, and uncover.
---
marp: true
theme: uncover
---
Tweaking Theme with CSS
Use the style global directive or a <style> tag to override theme styles. Use <style scoped> to apply CSS to only the current slide.
---
marp: true
theme: default
style: |
section { background-color: #fefefe; }
h1 { color: #333; }
---
<style scoped>
section {
background: linear-gradient(to bottom, #67b8e3, #0288d1);
color: white;
}
</style>
Class-Based Styling
Use the class directive to apply theme-specific layouts:
<!-- _class: lead -->
# Centered Lead Slide
Image Syntax
Marp extends Markdown image syntax with keywords in the alt text.
Resizing
Image Filters
Apply CSS filters via alt text keywords:
| Filter | Example |
|---|
blur |  |
brightness |  |
contrast |  |
drop-shadow |  |
grayscale |  |
hue-rotate |  |
invert |  |
opacity |  |
saturate |  |
sepia |  |
Combine multiple filters: 
Background Images
Add bg to the alt text to use an image as a slide background:
Background Size
| Keyword | Effect |
|---|
cover | Scale to fill slide (default) |
contain | Scale to fit slide |
fit | Alias for contain |
auto | Original size |
x% | Scale by percentage, e.g. 150% |
Multiple Backgrounds
Multiple bg images arrange horizontally by default:
Use vertical for vertical arrangement:
Split Backgrounds
Use left or right to create a split layout (image on one side, content on the other):
# Content on the right side
Specify split size with a percentage:
# Content takes up 67% of the slide
Fitting Header
Use <!-- fit --> inside a heading to auto-scale text to fit one line:
# <!-- fit --> This Long Title Will Shrink to Fit
Combine with headingDivider for Takahashi-style one-word-per-slide decks:
---
marp: true
theme: uncover
headingDivider: 1
---
# <!-- fit --> Takahashi-style presentation
# <!-- fit --> One idea per slide
Fragmented Lists
Fragmented lists appear incrementally in HTML export only (not PDF/PPTX).
Use * instead of - for bullet lists:
* Item appears first
* Then this item
* Then this one
Use ) instead of . for ordered lists:
1) First
2) Second
3) Third
Heading Divider
Automatically split slides at headings of a specified level using the headingDivider directive:
---
marp: true
headingDivider: 2
---
# Main Title
Introduction text
## Topic A
Content for topic A
## Topic B
Content for topic B
headingDivider: 2 splits at heading levels 1 and 2. Use an array for specific levels only: headingDivider: [1, 3].
Math Typesetting
Marp supports math rendering with MathJax (default) or KaTeX.
Inline Math
Euler's identity: $e^{i\pi} + 1 = 0$
Math Block
$$
f(x) = \int_{-\infty}^\infty \hat{f}(\xi)\,e^{2\pi i \xi x}\,d\xi
$$
Choosing a Library
Set math: mathjax (default) or math: katex in front matter.
Pagination
Enable page numbers with the paginate directive:
---
marp: true
paginate: true
---
Pagination Options
| Value | Page Number Visible | Counter Increments |
|---|
true | Yes | Yes |
false | No | Yes |
hold | Yes | No |
skip | No | No |
Skip Pagination on Title Slide
Use _paginate: false on the title slide to hide its page number, or move paginate: true to the second slide:
---
marp: true
paginate: true
_paginate: false
---
# Title Slide (no page number)
---
## Slide 2 (page number starts here)
Header and Footer
Set header and footer directives in front matter or HTML comments. They support inline Markdown (bold, italic, images). Wrap values in quotes for valid YAML.
---
marp: true
header: '**My Presentation**'
footer: '_© 2026 Author Name_'
---
Reset by setting to empty string: header: ''
Presenter Notes
Add presenter notes as HTML comments (after any directives):
# My Slide
Content here
<!-- This is a presenter note visible in presenter view -->
Exporting
VS Code: Install Marp for VS Code, then use Marp: Export Slide Deck from the command palette. Supports HTML, PDF, PPTX, PNG, JPEG.
Marp CLI:
brew install marp-cli
marp slides.md
marp slides.md -o slides.pdf
marp slides.md -o slides.pptx
marp slides.md --images png
marp slides.md --preview
Complete Example
---
marp: true
theme: default
paginate: true
_paginate: false
title: My Presentation
author: Author Name
---
# My Presentation
### Author Name — July 1, 2026
---
<!-- header: '**My Presentation**' -->
<!-- footer: '_Author Name_' -->
## Agenda
- Introduction
- Key Concepts
- Demo
---
## Key Concepts
- Marp converts **Markdown** to slides
- Supports themes, directives, and image syntax
- Export to HTML, PDF, or PPTX
---
## Split Layout
Content on the left, image on the right.
---
## Math
Euler's identity: $e^{i\pi} + 1 = 0$
---
<!-- _backgroundColor: #1a1a2e -->
<!-- _color: #eee -->
## <!-- fit --> Thank You!
Best Practices
- Always include
marp: true in front matter so Marp tools recognize the file
- Use
--- consistently to separate slides; keep an empty line before and after the ruler
- Set the
theme directive at the top of the deck for consistent styling
- Use scoped directives (
_ prefix) for one-off slide styling instead of changing and reverting values
- Keep slides focused — one idea per slide, minimal text
- Use
<!-- fit --> headers for impact slides with short phrases
- Test exports in your target format (PDF, PPTX) since some features like fragmented lists only work in HTML
- Declare
math directive explicitly (mathjax or katex) for consistent rendering
- Use
<style scoped> for per-slide CSS instead of global style overrides
- Quote directive values containing YAML special characters (colons, brackets) in single quotes
References
