Marp — Markdown Presentations

Use when creating slide decks, presentations, product requirement docs with diagrams, or converting markdown to PDF/PPTX/HTML slides. Triggers on "make a dec...

Security Scan

The skill's instructions match its stated purpose (creating/converting Marp markdown slides); nothing in the SKILL.md asks for unrelated credentials or system-wide privileges.

Purpose & Capability

The SKILL.md instructs use of the Marp CLI, optional Chrome/Edge for PDF export, and (for diagrams) npm/@mermaid-js/mermaid-cli or a CDN-hosted mermaid script — all coherent with a Marp/presentation skill. The skill metadata, however, declares no required binaries or tools even though the instructions assume marp, a browser for PDF rendering, and optionally npm/mermaid tooling. This is an omission in metadata rather than a functional mismatch.

Instruction Scope

Instructions stay within the presentation conversion domain (how to write directives, export to PDF/PPTX/HTML, pre-render diagrams). They do recommend fetching mermaid via a CDN (https://cdn.jsdelivr.net) for HTML embeds and installing mermaid-cli via npm for pre-rendering. Those external fetches are expected for the stated functionality but are noteworthy because they introduce remote network dependencies.

Install Mechanism

There is no install specification in the registry entry (instruction-only skill), so the skill itself does not write to disk or run an installer. The SKILL.md suggests installing third-party tools (e.g., npm -g @mermaid-js/mermaid-cli) if the user wants to pre-render diagrams — that is normal and optional, not an installation performed by the skill.

Credentials

The skill requests no environment variables, credentials, or config paths. The functionality described does not require secrets. The only external dependencies are binaries and network resources (marp CLI, npm/mermaid-cli, browser for PDF export, and optional CDN JS), which are proportionate to a slide conversion tool.

Persistence & Privilege

The skill is not always-enabled and does not request persistent system privileges. It does not modify other skills or system-wide agent settings. Autonomous invocation is allowed (platform default) but not combined with other concerning flags.

Assessment

This skill appears to be what it says: a Marp/Markdown-to-slides guide. Before using it, note that the SKILL.md assumes you have or will install the Marp CLI and (for some features) a browser that can render to PDF and optionally npm/mermaid-cli. The guide also shows embedding mermaid via a public CDN (jsdelivr) — if you prefer not to load remote scripts, pre-render diagrams locally with mermaid-cli or avoid the HTML-embed approach. Also be aware that following the SKILL.md's npm install -g commands will modify your system environment; run them only in a trusted environment. If you want stricter assurance, ask the skill author to declare required binaries in metadata (marp, chrome/edge, npm) and to provide an offline/pre-rendering-first workflow to avoid CDN fetches.

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)

<!-- backgroundColor: #1a1a2e -->
<!-- color: white -->
<!-- class: lead -->
<!-- _class: invert -->   ← underscore prefix = this slide only (spot directive)
<!-- header: Flash Product Spec -->
<!-- footer: Confidential -->

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

GitHub markdown style, content vertically centered. Clean for technical docs.

gaia

Classic Marp look. Supports lead class (centered) and gaia class (alternate colors).

<!-- _class: lead -->      ← centered title layout
<!-- _class: gaia -->       ← alternate color scheme
<!-- _class: lead invert --> ← dark centered

uncover

Always centered, minimal. Good for talks.

Common to all themes

<!-- class: invert -->  ← dark mode variant
<!-- size: 4:3 -->      ← 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](image.png)              <!-- width 200px -->
![h:150](image.png)              <!-- height 150px -->
![w:200 h:150](image.png)       <!-- both -->
![blur:3px](image.png)           <!-- CSS filter -->
![grayscale](image.png)          <!-- grayscale filter -->

Background images

![bg](image.png)                 <!-- full slide background -->
![bg contain](image.png)        <!-- fit inside slide -->
![bg cover](image.png)          <!-- cover entire slide -->
![bg fit](image.png)            <!-- alias for contain -->
![bg 50%](image.png)            <!-- 50% size -->
![bg right](image.png)          <!-- split: image right, content left -->
![bg left:40%](image.png)       <!-- split: image left 40%, content right -->

Multiple backgrounds

![bg](image1.png)
![bg](image2.png)
![bg](image3.png)
<!-- Shows side-by-side -->

Split backgrounds (content + image)

![bg right:60%](diagram.png)

## Architecture

- Component A talks to B
- B stores in database
- C reads from cache

<!-- Image takes 60% right, text takes 40% left -->

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

<!-- _class: brand -->

# 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%](diagram.svg)

Approach 2: HTML embed with mermaid.js

---
marp: true
---

<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>

<div class="mermaid">
graph LR
    A[User] --> B[Flash App]
    B --> C[API]
    C --> D[Database]
</div>

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

<!-- This is a presenter note. Won't appear on slide. -->
<!-- Use marp -s to serve and press P for presenter view. -->

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; }
---

<!-- _class: cover -->

# 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](./diagrams/user-flow.svg)

1. User opens Flashcard tab
2. Selects amount
3. Confirms creation
4. Receives Cashu token

---

## Architecture

![bg contain](./diagrams/architecture.svg)

---

## 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  — the bg keyword is required
Styles not applying	Check CSS selector — slides are <section> elements
Directives not working	Must be in HTML comment <!-- key: value --> or front-matter
Split background wrong side	 = image right;  = image left

Links

• Docs: https://marp.app
• Marpit (framework): https://marpit.marp.app
• CLI: https://github.com/marp-team/marp-cli
• VS Code extension: marp-team.marp-vscode