# Marp Slide

> Use when users request slide creation, presentations, or Marp documents. Creates professional Marp slides with 7 themes (default, minimal, colorful, dark, gradient, tech, business). Supports custom themes, image layouts, and "make it look good" requests.

- Skill: `matrixfounder/marp-slide` (Agent Skill, multi-file: 34 files)
- Install (CLI): `npx skillmds@latest add matrixfounder/marp-slide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixfounder/marp-slide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: MatrixFounder (https://skillmd.com/u/matrixfounder)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/matrixfounder/marp-slide

---


# Marp Slide Creator

Create professional, visually appealing Marp presentation slides with 7 pre-designed themes and built-in best practices.

## When to Use This Skill

Use this skill when the user:
- Requests to create presentation slides or Marp documents
- Asks to "make slides look good" or "improve slide design"
- Provides vague instructions like "良い感じにして" (make it nice) or "かっこよく" (make it cool)
- Wants to create lecture or seminar materials
- Needs bullet-point focused slides with occasional images

## Red Flags (Anti-Rationalization)

**STOP and READ if you are thinking:**
- "I know Marp syntax well enough, no need to read the references" → **WRONG**. Always read `references/marp-syntax.md` and the relevant template. Marp image syntax and directives have specific rules that differ from standard Markdown.
- "I'll just use the default theme, the user didn't specify" → **WRONG**. Infer the theme from content type using the Quick Start theme selection rules (technical → tech, business → business, creative → colorful/gradient, academic → minimal). Only fall back to default after inference fails.
- "I'll write the CSS from scratch instead of using the template" → **WRONG**. Templates contain tested, embedded CSS. Modifying CSS without reading `references/theme-css-guide.md` produces broken slides.

## Rationalization Table

| Agent Excuse | Reality |
|---|---|
| "The slide content is simple, I don't need a template" | Templates embed tested CSS. Without them, slides render with no styling in Marp. |
| "I'll combine all content onto fewer slides for efficiency" | Dense slides violate the 3-5 bullet points rule and destroy readability. |
| "The user will fix the image syntax later" | Broken Marp image directives (e.g., missing size or path) silently fail — the user sees nothing, not an error. |
| "I already checked best practices on a previous run" | Best practices are re-read per invocation. Memory does not persist between sessions. |

## Execution Mode
- **Mode**: `prompt-first` for content-creation; optional local-venv `scripts/render` for rendering.
- **Rationale**: Content-creation (picking templates, writing Marp-compatible markdown) is prompt-first and needs no runtime. Rendering to `.pptx/.pdf/.html/.png/.jpeg` is handled by an optional Python wrapper (`scripts/render.py`, invoked through a local venv) that pre-processes mermaid diagrams with a locally-installed `mmdc` before calling a locally-installed `marp-cli`. All rendering dependencies live under `scripts/.venv/` and `scripts/node_modules/` — nothing is installed globally.

## Script Contract
- **Input**: a Marp-compatible `.md` file (positional arg to `scripts/render.py`).
- **Flags**: `--format {pptx,pdf,html,png,jpeg}` (default `pptx`), `--output PATH`, `--no-mermaid`, `--strict-mermaid`, `--theme NAME`.
- **Output**: single file in the requested format at `--output` (or `<input_stem>.<format>` next to the input).
- **Side effects**: per-deck cache directory `<input_stem>_assets/` with `diagram-<sha1>.mmd` and `.svg` for each unique mermaid block. Re-runs reuse cached SVGs.
- **Binary resolution**: `marp` and `mmdc` are resolved from `scripts/node_modules/.bin/` (local-venv install); falls back to `PATH` if absent. System-wide installs are **not** required.
- **Exit codes**: `0` success · `1` bad args / missing input · `2` marp CLI unavailable (run `install.sh`) · `3` marp rendering failed · `4` mermaid preprocessing failed AND `--strict-mermaid` was set.

## Safety Boundaries
- **Scope**: Create or modify only the Marp `.md` file the user requested. Do not modify existing templates or CSS assets in the skill directory.
- **Output Location**: Save output to the user's working directory or the location they specify. Do not hardcode output paths.
- **No External Fetching**: Do not download images or external resources unless the user explicitly provides URLs and requests it.
- **Template Integrity**: Read templates from `assets/` as references. Never overwrite them.
- **Rendering Trust**: `scripts/render.py` always invokes marp with `--allow-local-files`, which puts every file readable by the current user within reach of the deck being rendered. Only render `.md` files you trust; do not run the renderer on decks from untrusted sources.

## Validation Evidence
- **Primary**: The output `.md` file contains valid Marp frontmatter (`marp: true`, `theme`, `paginate` directives).
- **Secondary**: Every slide uses `---` separators, title slide has `<!-- _class: lead -->`, and image directives use Marp syntax (not standard Markdown).
- **Quality Gate**: All items in the Quality Checklist (below) pass before delivering to the user.

## Quick Start

### Step 1: Select Theme

First, determine the appropriate theme based on the user's request and content.

**Quick theme selection:**
- **Technical/Developer content** → tech theme
- **Business/Corporate** → business theme
- **Creative/Event** → colorful or gradient theme
- **Academic/Simple** → minimal theme
- **General/Unsure** → default theme
- **Dark background preferred** → dark or tech theme

For detailed theme selection guidance, read `references/theme-selection.md`.

### Step 2: Create Slides

1. **Read relevant references first**:
   - Always start by reading `references/marp-syntax.md` for basic syntax
   - For images: `references/image-patterns.md` (official Marpit image syntax)
   - For advanced features (math, emoji): `references/advanced-features.md`
   - For custom themes: `references/theme-css-guide.md`

2. Copy content from the appropriate template file:
   - `assets/template-basic.md` - Default theme (most common)
   - `assets/template-minimal.md` - Minimal theme
   - `assets/template-colorful.md` - Colorful theme
   - `assets/template-dark.md` - Dark mode theme
   - `assets/template-gradient.md` - Gradient theme
   - `assets/template-tech.md` - Tech/code theme
   - `assets/template-business.md` - Business theme

3. Read `references/best-practices.md` for quality guidelines

4. Structure content following best practices:
   - Title slide with `<!-- _class: lead -->`
   - Concise h2 titles (5-7 characters in Japanese; 2-5 words in English)
   - 3-5 bullet points per slide
   - Adequate whitespace

5. Add images if needed using patterns from `references/image-patterns.md`

6. Save to the user's working directory (or their specified output path) with `.md` extension

### Step 3: Render (optional)

If the caller wants `.pptx`, `.pdf`, `.html`, or image output — not just the `.md` — use the skill's own renderer:

    bash scripts/install.sh            # one-time: creates scripts/.venv + scripts/node_modules
    scripts/render INPUT.md            # default: .pptx with mermaid pre-rendered
    scripts/render INPUT.md --format pdf

The renderer:
- runs entirely from a **local** Python venv (`scripts/.venv/`) and **local** `node_modules/` (`scripts/node_modules/`) — nothing installed globally;
- handles mermaid diagrams (pre-rendered to SVG via `mmdc` before marp sees them) — closes the marp-core gap that leaves mermaid as raw code blocks;
- supports formats `pptx`, `pdf`, `html`, `png`, `jpeg`;
- caches SVG diagrams in `<input>_assets/` by SHA1 of the mermaid source (re-runs skip `mmdc`);
- degrades gracefully when `mmdc` is absent (prints a WARN, leaves mermaid as code).

See `scripts/README.md` for CLI flags, CI integration, and troubleshooting. See `## Dependencies` below for what `install.sh` sets up.

## Available Themes

### 1. Default Theme
**Colors**: Beige background, navy text, blue headings
**Style**: Clean, sophisticated with decorative lines
**Use for**: General seminars, lectures, presentations
**Template**: `template-basic.md`

### 2. Minimal Theme
**Colors**: White background, gray text, black headings
**Style**: Minimal decoration, wide margins, light fonts
**Use for**: Content-focused presentations, academic talks
**Template**: `template-minimal.md`

### 3. Colorful & Pop Theme
**Colors**: Pink gradient background, multi-color accents
**Style**: Vibrant gradients, bold fonts, rainbow accents
**Use for**: Youth-oriented events, creative projects
**Template**: `template-colorful.md`

### 4. Dark Mode Theme
**Colors**: Black background, cyan/purple accents
**Style**: Dark theme with glow effects, eye-friendly
**Use for**: Tech presentations, evening talks, modern look
**Template**: `template-dark.md`

### 5. Gradient Background Theme
**Colors**: Purple/pink/blue/green gradients (varies per slide)
**Style**: Different gradient per slide, white text, shadows
**Use for**: Visual-focused, creative presentations
**Template**: `template-gradient.md`

### 6. Tech/Code Theme
**Colors**: GitHub-style dark background, blue/green accents
**Style**: Code fonts, Markdown-style headers with # symbols
**Use for**: Programming tutorials, tech meetups, developer content
**Template**: `template-tech.md`

### 7. Business Theme
**Colors**: White background, navy headings, blue accents
**Style**: Corporate presentation style, top border, table support
**Use for**: Business presentations, proposals, reports
**Template**: `template-business.md`

## Handling "Make It Look Good" Requests

When users give vague instructions like "良い感じにして", "かっこよく", or "make it cool":

1. **Infer theme from content**:
   - Business content → business theme
   - Technical content → tech or dark theme
   - Creative content → gradient or colorful theme
   - General → default theme

2. **Apply best practices automatically**:
   - Shorten titles to 5-7 characters (Japanese) or 2-5 words (English)
   - Limit bullet points to 3-5 items
   - Add adequate whitespace
   - Use consistent structure

3. **Enhance visual hierarchy**:
   - Use h3 for sub-sections when appropriate
   - Break up dense text into multiple slides
   - Ensure logical flow (intro → body → conclusion)

4. **Maintain professional tone**:
   - Match formality to content
   - Use parallel structure in lists
   - Keep technical terms consistent

## Image Integration

For slides with images, consult `references/image-patterns.md` for detailed syntax.

Common patterns:
- **Side image**: `![bg right:40%](image.png)` - Image on right, text on left
- **Centered**: `![w:600px](image.png)` - Centered with specific width
- **Full background**: `![bg](image.png)` - Full-screen background
- **Multiple images**: Multiple `![bg]` declarations

Example lecture pattern:
```markdown
## Slide Title

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

- Explanation point 1
- Explanation point 2
- Explanation point 3
```

## File Output

Save the final Marp file with `.md` extension to the user's working directory or a path they specify:
- `presentation.md`
- `seminar-slides.md`
- `lecture-materials.md`

## Quality Checklist

Before delivering slides, verify:
- [ ] Theme selected appropriately for content
- [ ] CSS theme is embedded in the file
- [ ] Title slide uses `<!-- _class: lead -->`
- [ ] All h2 titles are concise (5-7 chars Japanese / 2-5 words English)
- [ ] Bullet points are 3-5 items per slide
- [ ] Images use proper Marp syntax
- [ ] File saved to user's working directory or specified path
- [ ] Content follows best practices

## Dependencies

The **content-creation** portion of this skill (picking templates, writing Marp-compatible markdown) has **no runtime dependencies** — it's prompt-first, produces a `.md` file, and is portable across any environment.

The **rendering** portion (optional; see Step 3 above) is fully **local** — no global installs. `bash scripts/install.sh` sets up everything under `scripts/.venv/` and `scripts/node_modules/`:

| Dependency | Where installed | How |
|------------|-----------------|-----|
| Python 3.10+ | host | system package manager |
| Node.js 18+ | host | https://nodejs.org/ |
| Python venv | `scripts/.venv/` | `install.sh` → `python3 -m venv` (stdlib only, no pip packages) |
| `@marp-team/marp-cli` | `scripts/node_modules/` | `install.sh` → `npm install` (local, not `-g`) |
| `@mermaid-js/mermaid-cli` | `scripts/node_modules/` | `install.sh` → `npm install` (local, not `-g`). Optional: without it mermaid degrades to code. |
| Headless Chromium | Puppeteer cache | auto-downloaded by marp/mmdc on first `npm install` (~200 MB) |

Run `bash scripts/install.sh` once to install and verify all of the above. The script is idempotent — safe to re-run. To fully uninstall, just delete `scripts/.venv/` and `scripts/node_modules/`.

### CI / sandboxed environments

Set these env vars before running `install.sh` on networks that block the Puppeteer Chromium download:

    export PUPPETEER_SKIP_DOWNLOAD=true
    export PUPPETEER_EXECUTABLE_PATH=/path/to/chromium

### Cyrillic / CJK / RTL text in mermaid diagrams

`mmdc`'s default font does not contain all Unicode ranges — non-Latin text in a mermaid diagram may render as boxes. Fix via a mermaid config JSON, applied one of two ways:

**Auto-load:** drop a `mermaid-config.json` into `scripts/`; `render.py` picks it up on every run.

**Per-run:** pass `--mermaid-config PATH` to `scripts/render`.

    # Example config
    cat > scripts/mermaid-config.json <<'EOF'
    { "theme": "default", "themeVariables": { "fontFamily": "Arial, sans-serif" } }
    EOF

The config content + `mmdc --version` are folded into the SHA1 cache key, so cached SVGs invalidate automatically when either changes. See `scripts/README.md` for details.

## References

### Core Documentation
- **Marp syntax**: `references/marp-syntax.md` - Basic Marp/Marpit syntax (directives, frontmatter, pagination, etc.)
- **Image patterns**: `references/image-patterns.md` - Official image syntax (bg, filters, split backgrounds)
- **Theme CSS guide**: `references/theme-css-guide.md` - How to create custom themes based on Marpit specification
- **Advanced features**: `references/advanced-features.md` - Math, emoji, fragmented lists, Marp CLI, VS Code
- **Official themes**: `references/official-themes.md` - default, gaia, uncover themes documentation

### Quality & Selection Guides
- **Theme selection**: `references/theme-selection.md` - How to choose the right theme for content
- **Best practices**: `references/best-practices.md` - Quality guidelines for "cool" slides

### Templates & Assets
- **Templates**: `assets/template-*.md` - Starting points with embedded CSS for each theme (7 themes)
- **Standalone CSS**: `assets/theme-*.css` - CSS files for reference (already embedded in templates)

### Renderer & Fixtures
- **Renderer operator notes**: `scripts/README.md` — CLI flags, install, CI, troubleshooting
- **Fixtures**:
  - `examples/fixture-mermaid-minimal.md` — minimal smoke (one mermaid mindmap)
  - `examples/fixture-mermaid-full-deck.md` — realistic 10-slide deck with Cyrillic mermaid content
  - `examples/fixture-mermaid-multi.md` — 3 mermaid blocks (2 unique + 1 duplicate), guards regex and SHA1 dedup

### Official External Links
- **Marp Official Site**: https://marp.app/
- **Marpit Directives**: https://marpit.marp.app/directives
- **Marpit Image Syntax**: https://marpit.marp.app/image-syntax
- **Marpit Theme CSS**: https://marpit.marp.app/theme-css
- **Marp Core GitHub**: https://github.com/marp-team/marp-core
- **Marp CLI GitHub**: https://github.com/marp-team/marp-cli