| name | marpit-slides |
| description | Write Markdown slide decks using Marpit/Marp syntax and style them with CSS themes. Use this skill whenever the user wants to create presentation slides in Markdown, mentions Marp or Marpit, asks for a ".md slide deck", wants to write slides using horizontal rulers (---), asks about Marp directives, image syntax, background images, split backgrounds, themes, or any Markdown-to-slide workflow. Also trigger when the user wants to style or theme Marp slides, add pagination/headers/footers, use scoped styles, create fragmented lists, or convert existing content into a Marp presentation. If the user says "slides", "deck", "presentation" and mentions Markdown or Marp, use this skill. |
Marpit/Marp Slide Writing Skill
This skill helps you write Markdown slide decks using the Marpit framework (and its superset Marp Core). The output is a .md file that can be rendered by Marp CLI, Marp for VS Code, or any Marpit-based tool into HTML, PDF, or PPTX.
Quick Start Structure
Every Marp slide deck starts with a YAML front-matter block and uses --- to separate slides:
---
marp: true
theme: default
paginate: true
---
# Slide 1 Title
Content here
---
# Slide 2 Title
More content
The marp: true flag enables Marp features in VS Code and other tools. It is not a Marpit directive per se, but is standard practice and should always be included.
Slide Separation
Slides are split by horizontal rulers. The standard --- requires an empty line before it per CommonMark spec. Alternatives that don't need empty lines:
___ (underscores)*** (asterisks)- - - (spaced dashes)
Directives
Directives control slide-deck behavior. They are written as YAML inside HTML comments or in the front-matter. Read the full reference in references/DIRECTIVES.md before using advanced directive features.
Where to write directives
- Front-matter (top of file, between
--- rulers) — for global settings
- HTML comments anywhere in the Markdown:
<!-- theme: default -->
<!-- paginate: true -->
Directive scoping
- Global directives: Apply to the entire deck. Set once (last value wins if duplicated). Examples:
theme, style, headingDivider.
- Local directives: Apply from the current slide onward. Examples:
paginate, header, footer, class, color, backgroundColor.
- Spot directives: Prefix with
_ to apply to the current slide only, e.g., _class: invert, _paginate: false, _backgroundColor: black.
Key directives
| Directive | Scope | Purpose |
|---|
theme | Global | Select theme name |
style | Global | Inject CSS (alternative to <style> tag) |
headingDivider | Global | Auto-split slides at heading levels (1-6 or array) |
paginate | Local | Show page numbers (true/false) |
_paginate | Spot | false hides number; skip hides but still counts |
header | Local | Set header text |
footer | Local | Set footer text |
class | Local | Set CSS class on slide's <section> |
color | Local | Set text color |
backgroundColor | Local | Set background color |
backgroundImage | Local | Set background image via CSS value |
backgroundSize | Local | Set background-size style |
backgroundPosition | Local | Set background-position style |
Example: Title slide without pagination, then enable it
---
marp: true
theme: default
---
# My Presentation
### By Author Name
---
<!-- paginate: true -->
# First Content Slide
This slide and all after it will have page numbers.
Image Syntax
Marpit extends Markdown image syntax  with keywords in the alt text. Read references/IMAGE_SYNTAX.md for the full reference.
Resizing
Shorthand: w for width, h for height.
CSS Filters
Add filter keywords to the alt text:
Available filters: blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, opacity, saturate, sepia.
Background Images
Add the bg keyword to make an image a slide background:
Background size keywords: cover (default), contain, fit (alias for contain), auto, or a percentage like 50%.
Background Color
Pass a CSS color value as the URL:
Split Backgrounds
Use bg left or bg right to split the slide between content and a background image:
# Content on the right side
Specify split ratio: 
Multiple Backgrounds
Multiple ![bg] images in one slide tile side-by-side (horizontal by default). Add vertical keyword for vertical stacking:
Multiple backgrounds require inline SVG mode to be enabled (it is enabled by default in Marp Core/CLI).
Styling Slides
Inline <style> tags
A <style> tag in Markdown applies in the context of the theme CSS — it's like adding rules to the theme:
---
marp: true
theme: default
---
<style>
section {
background-color: #fefefe;
font-family: 'Helvetica Neue', sans-serif;
}
h1 {
color: #2d3436;
}
</style>
# Styled Slide
Scoped styles
Use <style scoped> for one-shot styling that applies only to the current slide:
# Normal Slide
---
<style scoped>
h1 { color: red; }
section { background: black; color: white; }
</style>
# This slide only is styled differently
The style directive
An alternative to <style> tags (useful to keep Markdown clean in other editors):
---
marp: true
theme: default
style: |
section {
background-color: #fdf6e3;
}
h1 {
color: #b58900;
}
---
Custom classes
Define classes in your style, then apply with the class directive:
<style>
section.lead {
text-align: center;
justify-content: center;
}
section.invert {
background: #333;
color: #fff;
}
</style>
---
<!-- _class: lead -->
# Centered Title Slide
---
<!-- _class: invert -->
# Dark Slide
Theme CSS Fundamentals
When creating a custom theme, the key concept is that <section> elements are the viewport for each slide. Read references/THEME_CSS.md for the full guide.
Minimal custom theme
---
marp: true
---
<style>
/* @theme my-custom */
section {
width: 1280px;
height: 720px;
font-size: 28px;
padding: 40px;
background: #fff;
color: #333;
}
h1 { color: #0366d6; font-size: 48px; }
h2 { color: #586069; font-size: 36px; }
</style>
# My Presentation
The @theme comment is required when defining a standalone theme file. When using <style> inline in a deck, you don't strictly need it, but it's good practice.
Slide size
Width and height on section define the slide dimensions (default: 1280×720). Must use absolute units (px, cm, in, pt).
section { width: 960px; height: 720px; }
section { width: 1280px; height: 720px; }
Pagination styling
Style page numbers via section::after:
section::after {
font-weight: bold;
font-size: 14px;
content: attr(data-marpit-pagination) ' / ' attr(data-marpit-pagination-total);
}
Header and footer styling
header, footer {
font-size: 14px;
color: #999;
}
header { top: 10px; }
footer { bottom: 10px; }
Fragmented Lists
Use * (asterisk) for bullet lists or ) for ordered lists to create fragmented (step-by-step reveal) lists. This works in HTML export only (not PDF/PPTX).
# Regular list
- One
- Two
- Three
---
# Fragmented list (reveals one-by-one)
* One
* Two
* Three
---
# Fragmented ordered list
1) First
2) Second
3) Third
Presenter Notes
HTML comments that are NOT parsed as directives become presenter notes:
# My Slide
Content here
<!-- This is a presenter note — it won't appear on the slide -->
headingDivider
Auto-split slides at headings instead of manually writing ---:
---
marp: true
headingDivider: 2
---
# Section 1
## Topic A
Content for Topic A
## Topic B
Content for Topic B
This produces 3 slides: "Section 1", "Topic A", and "Topic B". Accepts a single level number or an array like [1, 2].
Built-in Themes (Marp Core)
Marp Core provides three themes: default, gaia, and uncover. Each supports the invert class for a dark variant and lead class for centered title slides (gaia only has gaia class for an alternative color scheme).
---
marp: true
theme: gaia
class: lead
---
# Title Slide
---
<!-- _class: invert -->
# Dark variant
Workflow
When generating a Marp slide deck:
- Start with front-matter:
marp: true, theme, and any global directives
- Write slide content separated by
---
- Add a
<style> block for custom styling if needed
- Use directives (HTML comments) for per-slide configuration
- Save as
.md and output to /mnt/user-data/outputs/
Always produce a complete, ready-to-render .md file. The user can open it in VS Code with Marp extension, or convert via npx @marp-team/marp-cli slide-deck.md.
Reference Files
For detailed syntax on specific topics, read:
references/DIRECTIVES.md — Full directive reference with all scoping rulesreferences/IMAGE_SYNTAX.md — Complete image resizing, filters, backgrounds, and split layoutsreferences/THEME_CSS.md — Creating custom themes, slide sizing, pagination, headers/footers
