Marp

Marp Slide Deck Generator

Quick Start: Add YAML front-matter marp: true → write Markdown with --- between slides → run marp deck.md --pptx → done.

---
marp: true
theme: default
paginate: true
---

# Title Slide

Speaker · Date

---

# Section Slide

- Point 1
- Point 2

Why Marp

How this skill ties into the rest of the repo

Marp is the glue that takes diagram outputs from the other skills and assembles them into a deliverable deck:

Key insight: the existing skills produce diagrams in their native formats; Marp doesn't replace them. It composes them into a deck.

Critical Rules

Rule 1: YAML front-matter is required

The first lines of the file must be:

---
marp: true
---

Without marp: true, the file is treated as plain Markdown. Other useful front-matter keys:

---
marp: true
theme: default            # default | gaia | uncover | <custom name>
size: 16:9                # 16:9 | 4:3 | A4 | <width>x<height>px
paginate: true            # show slide numbers
header: 'Project Apollo'  # appears on every slide
footer: 'Confidential'
backgroundColor: '#fff'
class: lead               # apply 'lead' class to all slides
---

Rule 2: Slides separated by ---

A bare --- on its own line ends one slide and starts the next. Do not put --- at the end of the file.

---
marp: true
---

# Slide 1

content

---

# Slide 2

Rule 3: Per-slide directives use HTML comments

Override front-matter on a single slide with a special comment:

<!-- _class: lead -->
<!-- _backgroundColor: #1e293b -->
<!-- _color: white -->

# Cover Slide

Underscore prefix = "this slide only". No underscore = "this slide and all that follow until overridden".

Rule 4: Mermaid needs a flag

Mermaid blocks render only when you pass --html and use the math/mermaid plugin, or use a Marp theme with Mermaid baked in. The shortest working invocation:

npx @marp-team/marp-cli@latest deck.md --pptx --html

For complex Mermaid features (C4, sequence with autoNumber, etc.), pre-render to SVG via the mermaid skill's CLI and embed the SVG instead. This also makes the deck reproducible without internet.

Rule 5: Image sizing via Marp's image syntax

Marp extends Markdown image syntax with sizing/positioning hints:

![w:600](architecture.svg)        # width 600px
![h:400](diagram.png)             # height 400px
![bg](cover.jpg)                  # full-slide background
![bg right:40%](architecture.svg) # right 40% of slide
![bg fit](logo.png)               # fit, preserve aspect

bg is the killer feature — it makes a single image fill the slide background, perfect for hero diagrams.

Rule 6: Two-column layouts via HTML or columns plugin

Markdown alone doesn't do columns. Three options:

<div class="columns">
<div>

## Left

- bullet
- bullet

</div>
<div>

## Right

```mermaid
flowchart LR
  a --> b

For repeated use, put the `<style>` block in front-matter `style:` or a custom theme.

### Rule 7: Speaker notes via HTML comment
```markdown
# Slide

content

<!--
Speaker notes go here. They show in PowerPoint's notes pane after .pptx export.
-->

Common slide patterns for architecture decks

---
marp: true
theme: default
paginate: true
size: 16:9
header: 'Architecture Review · 2026 Q2'
---

<!-- _class: lead -->
<!-- _backgroundColor: #0f172a -->
<!-- _color: white -->

# HR Onboarding Platform
## Architecture Review

Sheker · April 2026

---

# Agenda

1. Context
2. Container architecture
3. Data flow
4. Open questions

---

# System Context

![bg right:55%](diagrams/system-context.svg)

- 3 internal users: candidate, recruiter, manager
- 4 external SaaS dependencies
- One enterprise boundary: Acme

---

# Container Architecture

![bg fit](diagrams/container.svg)

<!-- Speaker notes:
Walk through API Gateway -> Onboarding Service -> Postgres path.
Note Temporal as the orchestrator for long-running workflows.
-->

---

# Onboarding Sequence

```mermaid
sequenceDiagram
  Candidate->>API: Submit application
  API->>Onboarding: createApplication
  Onboarding->>Kafka: ApplicationSubmitted
  Kafka-->>Workflow: consume
  Workflow->>Checkr: Run background check
  Checkr-->>Workflow: webhook (clear)
  Workflow->>Notify: Send offer email

Open Questions

• Should onboarding state live in Temporal or Postgres?
• Move Checkr integration behind feature flag?

## Examples

| File | Demonstrates |
|---|---|
| [examples/architecture-review.md](examples/architecture-review.md) | Full deck pulling diagrams from mermaid + c4 + architecture skills |

## Export commands

```bash
# PowerPoint (.pptx) — primary use case
npx @marp-team/marp-cli@latest deck.md --pptx --html

# PDF — for distribution where PowerPoint isn't installed
npx @marp-team/marp-cli@latest deck.md --pdf --html

# Editable .pptx (slides are vector, not images)
npx @marp-team/marp-cli@latest deck.md --pptx --html --pptx-editable

# Per-slide PNGs (for embedding in other tools)
npx @marp-team/marp-cli@latest deck.md --images png

# Watch mode for live editing
npx @marp-team/marp-cli@latest deck.md -w --pptx --html

--pptx-editable is important: without it, each slide is rasterized to an image inside the .pptx, which means stakeholders can't tweak text in PowerPoint. With it, text and shapes stay editable. It requires libreoffice on the PATH — install with apt install libreoffice (Linux) or brew install --cask libreoffice (mac). Without LibreOffice, fall back to plain --pptx (rasterized, but works everywhere).

Best Practices

1. Pre-render diagrams to SVG/PNG. Inline Mermaid is convenient but breaks if your reviewer opens the deck offline or in a Marp version mismatch. Pre-rendered SVGs are bulletproof.
2. Use _class: lead for cover and section slides — built-in Marp themes give them centered, larger typography automatically.
3. One idea per slide. A C4 Container diagram on one slide, with the implications/tradeoffs on the next slide as bullets. Don't crowd.
4. Speaker notes via HTML comments survive .pptx export and show up in PowerPoint's notes pane.
5. Custom theme for company branding. A 50-line CSS file (company.css) → --theme-set company.css → consistent fonts and colors across every deck.
6. Pin the Marp version. npx @marp-team/marp-cli@4.0.4 rather than @latest for repeatable rendering in CI.
7. Generate decks in CI. Architecture review every sprint? Commit the .md, render the .pptx in CI, attach to the calendar invite. Far better than manually maintaining a PowerPoint file.