| name | md2prez |
| description | Generate a professional HTML slide presentation from Markdown using Marp CLI. Use this skill when the user asks to create a presentation, slides, or a deck from a document. Supports Mermaid diagrams (pre-rendered to PNG), custom CSS themes, background images, speaker notes, and PDF export. Targets developer and architect audiences with clean, structured visuals. |
Markdown to Presentation Generator (Marp)
Generate professional HTML slide presentations from Markdown using Marp CLI, with Mermaid diagram support and a custom CSS theme.
When to Use
Use this skill when the user asks to:
- Create a presentation or slide deck
- Generate slides from a document or markdown file
- Build a deck for a talk, workshop, or meeting
- Export slides to HTML or PDF
Prerequisites
Ensure these tools are available (install if missing):
| Tool | Install Command | Purpose |
|---|
| @marp-team/marp-cli | npm install -g @marp-team/marp-cli or local in package.json | Markdown → HTML/PDF slides |
| mmdc | npm install -g @mermaid-js/mermaid-cli | Mermaid diagram → PNG rendering |
Project Structure
prez/
├── slides.md # Slide content (Marp markdown)
├── theme.css # Custom CSS theme
├── images/ # Pre-rendered Mermaid diagrams (PNG)
├── package.json # Scripts for dev/build/pdf
├── .gitignore # Exclude node_modules/, dist/
└── dist/ # Build output (git-ignored)
Procedure
Step 1 — Initialize Project
Create package.json:
{
"name": "presentation-name",
"private": true,
"scripts": {
"dev": "npx @marp-team/marp-cli --theme theme.css --html --allow-local-files -s .",
"build": "npx @marp-team/marp-cli --theme theme.css --html --allow-local-files slides.md -o dist/index.html",
"pdf": "npx @marp-team/marp-cli --theme theme.css --html --allow-local-files --pdf slides.md -o dist/slides.pdf"
},
"dependencies": {
"@marp-team/marp-cli": "^4.0.0"
}
}
Create .gitignore:
node_modules/
dist/
Run npm install.
Step 2 — Create Custom CSS Theme
Create theme.css. The file must start with /* @theme theme-name */ and @import 'default';.
Below is the standard professional "fabric" theme — adapt colors to match the topic:
@import 'default';
:root {
--primary: #0078d4;
--primary-dark: #003f6b;
--heading-dark: #1e3a5f;
--text: #1a1a2e;
}
section {
font-family: 'Segoe UI', system-ui, sans-serif;
font-size: 23px;
padding: 50px 60px 40px;
background: #ffffff;
color: var(--text);
border-top: 4px solid var(--primary);
}
section::after {
color: #6b7280;
font-size: 13px;
}
h1 {
color: var(--primary);
font-size: 1.55em;
font-weight: 700;
border-bottom: 2px solid #e3f2fd;
padding-bottom: 6px;
margin-bottom: 14px;
}
h2 {
color: var(--heading-dark);
font-size: 1.2em;
font-weight: 600;
}
h3 {
color: var(--primary);
font-size: 1.0em;
font-weight: 600;
}
section.lead {
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
text-align: center;
background: linear-gradient(135deg, var(--primary) 0%, #005a9e 50%, var(--primary-dark) 100%);
color: white;
border-top: none;
}
section.lead h1 {
color: white;
font-size: 2.1em;
border-bottom: 3px solid rgba(255,255,255,0.3);
padding-bottom: 12px;
}
section.lead h2 {
color: rgba(255,255,255,0.85);
font-weight: 400;
font-size: 1.15em;
}
section.lead h3 {
color: rgba(255,255,255,0.7);
font-weight: 400;
}
section.divider {
display: flex;
flex-direction: column;
justify-content: center;
background: #f0f4f8;
border-top: 4px solid var(--primary);
border-left: 6px solid var(--primary);
}
section.divider h1 {
font-size: 1.9em;
border-bottom: none;
}
table {
width: 100%;
border-collapse: collapse;
font-size: 0.78em;
margin: 10px 0;
}
th {
background: var(--primary);
color: white;
padding: 7px 10px;
text-align: left;
font-weight: 600;
}
td {
padding: 5px 10px;
border-bottom: 1px solid #e5e7eb;
}
tr:nth-child(even) td {
background: #f8fafc;
}
code {
background: #f1f5f9;
color: var(--primary);
padding: 1px 5px;
border-radius: 3px;
font-family: 'Cascadia Mono', 'Consolas', monospace;
font-size: 0.82em;
}
ul, ol { margin: 6px 0; padding-left: 1.4em; }
li { margin: 3px 0; line-height: 1.45; }
strong { color: var(--primary); }
img {
border-radius: 4px;
display: block;
margin: 0 auto;
}
blockquote {
background: #e3f2fd;
border-left: 4px solid var(--primary);
padding: 10px 14px;
border-radius: 0 5px 5px 0;
margin: 10px 0;
font-size: 0.85em;
}
blockquote p { margin: 0; }
Step 3 — Pre-render Mermaid Diagrams
Marp does not support Mermaid natively. Render each diagram to PNG before writing slides.
New-Item -ItemType Directory -Path images -Force | Out-Null
$configFile = "$env:TEMP\puppeteer-marp.json"
Set-Content -Path $configFile -Value '{"args":["--no-sandbox","--disable-setuid-sandbox"]}'
# For each diagram, create a .mmd file, render, then delete the source
$mmdContent = @"
flowchart LR
A["Step 1"] --> B["Step 2"]
style A fill:#e3f2fd,stroke:#0078d4
style B fill:#c8e6c9,stroke:#2e7d32
"@
Set-Content -Path "images\example.mmd" -Value $mmdContent
& mmdc -i "images\example.mmd" -o "images\example.png" -p $configFile -b white -w 1400 -s 2
Remove-Item "images\example.mmd" -Force
Mermaid color palette (consistent across diagrams):
| Color | Hex Fill / Stroke | Usage |
|---|
| Blue | #e3f2fd / #0078d4 | Primary / platform |
| Green | #c8e6c9 / #2e7d32 | Allowed / success |
| Red | #ffcdd2 / #c62828 | Blocked / denied |
| Purple | #d1c4e9 / #7b1fa2 | Identity / users |
| Orange | #fff3e0 / #f57c00 | Decisions / external |
| Teal | #e0f2f1 / #00695c | On-premises / DNS |
Step 4 — Write slides.md
Front Matter
---
marp: true
theme: fabric
paginate: true
header: 'Presentation Title'
footer: 'Date or Event'
---
Slide Syntax Reference
Slide separator: --- on its own line.
Title slide (lead):
<!-- _class: lead -->
<!-- _paginate: false -->
<!-- _header: '' -->
<!-- _footer: '' -->
# Main Title
## Subtitle
### Date or Event
Section divider:
<!-- _class: divider -->
# Section Name
Description of this section
Regular slide with diagram on the right:
# Slide Title
- Bullet point 1
- Bullet point 2
> Callout box text
Full-width centered diagram:
# Slide Title
Closing slide:
<!-- _class: lead -->
<!-- _paginate: false -->
<!-- _header: '' -->
<!-- _footer: '' -->
# Thank You
### Questions?
Image Sizing Directives
| Directive | Effect |
|---|
 | Set width to 600px, auto-centered via CSS |
 | Set height to 400px |
 | Background image on right 45% of slide |
 | Background image on left 40% of slide |
 | Background image scaled to fit slide |
 | Background image at 70% of slide area |
Sizing guidelines:
bg right/left diagrams: use w:500 to w:560 for good readability- Full-width centered diagrams: use
w:600 to w:700 (never exceed w:750)
- Complex diagrams (E2E architecture): use
w:620 to w:680
Per-Slide Directives
Prefix with _ to apply to current slide only:
| Directive | Example |
|---|
<!-- _class: lead --> | Apply lead class to this slide |
<!-- _paginate: false --> | Hide page number |
<!-- _header: '' --> | Hide header |
<!-- _footer: 'Custom' --> | Override footer text |
<!-- _backgroundColor: #f0f4f8 --> | Custom background color |
Step 5 — Build
# Install dependencies
npm install
# Dev server with live reload (http://localhost:8080)
npm run dev
# Build to HTML
npx @marp-team/marp-cli --theme theme.css --html --allow-local-files slides.md -o dist/index.html
# Build to PDF (requires Chrome/Edge installed)
npx @marp-team/marp-cli --theme theme.css --html --allow-local-files --pdf slides.md -o dist/slides.pdf
Step 6 — Cleanup
Delete .mmd source files after rendering (keep PNGs in git for the presentation):
Remove-Item "images\*.mmd" -Force -ErrorAction SilentlyContinue
Two Theme Styles
Pick based on the audience and level of polish required:
| Style | When to use | Signature elements |
|---|
Standard (fabric) | Engineer-focused decks, internal reviews, where density > polish. Shown above. | Bullet lists, callouts, tables, right-side diagrams |
Editorial (fabric-editorial) | External/exec audiences, architecture briefs, "magazine-style" decks. Favors visuals over prose. | Cards grid, big-number stats, numbered steps, chapter markers, dark closing slide |
The standard style is fine for most decks. Reach for the editorial style when the user asks for something more polished, visual, or "less text-heavy".
Editorial Style
Principles
- More graphics, less text. Whenever a concept has 3+ bullets, consider turning it into a diagram, a cards grid, or a stats block.
- One chapter number per major section. Huge translucent numerals (e.g.,
01, 02) guide the reader's mental map.
- Asymmetric splits. Two-column layouts with
0.9fr 1.1fr ratios feel editorial, not corporate.
- Dark closing slide for visual punctuation.
- Tight title page: small "tag" above a big title, muted subtitle.
Editorial theme.css
@import 'default';
:root {
--ink: #0a1929;
--muted: #64748b;
--brand: #0078d4;
--accent: #00b4a6;
--warn: #e65100;
--danger: #c62828;
--success: #2e7d32;
--purple: #6f42c1;
}
section {
font-family: 'Inter', 'Segoe UI', system-ui, sans-serif;
font-size: 22px;
padding: 60px 70px 50px;
background: #ffffff;
color: var(--ink);
letter-spacing: -0.005em;
}
section::before {
content: ''; position: absolute; left: 0; top: 0; bottom: 0; width: 4px;
background: linear-gradient(180deg, var(--brand) 0%, var(--accent) 100%);
}
h1 { font-size: 2em; font-weight: 700; color: var(--ink); margin: 0 0 18px; }
h2 { font-size: 1.1em; font-weight: 500; color: var(--muted); margin: 0 0 24px; }
h3 { font-size: 0.95em; font-weight: 600; color: var(--brand); text-transform: uppercase; letter-spacing: 0.06em; margin: 18px 0 8px; }
section.lead { background: radial-gradient(1200px 600px at 20% 10%, #dbeafe 0%, #fff 60%); padding: 80px 90px; }
section.lead::before { display: none; }
section.lead h1 { font-size: 3.2em; line-height: 1.05; letter-spacing: -0.02em; }
section.lead .tag { display: inline-block; background: var(--ink); color: #fff; padding: 4px 12px; font-size: 0.7em; font-weight: 600; letter-spacing: 0.1em; text-transform: uppercase; border-radius: 4px; margin-bottom: 18px; }
section.chapter { background: var(--ink); color: #fff; padding: 80px 90px; }
section.chapter::before { display: none; }
section.chapter .num { position: absolute; right: 60px; bottom: 10px; font-size: 18em; line-height: 1; font-weight: 900; color: rgba(255,255,255,0.08); }
section.chapter h1 { color: #fff; font-size: 3em; }
.cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; margin-top: 12px; }
.cards.two { grid-template-columns: 1fr 1fr; }
.card { background: #f8fafc; border-left: 4px solid var(--brand); padding: 16px 18px; border-radius: 0 6px 6px 0; }
.card.teal { border-color: var(--accent); }
.card.red { border-color: var(--danger); }
.card.green { border-color: var(--success); }
.card.orange { border-color: var(--warn); }
.card.purple { border-color: var(--purple); }
.card-num { font-size: 0.65em; font-weight: 700; letter-spacing: 0.12em; color: var(--muted); text-transform: uppercase; margin-bottom: 4px; }
.card h3 { margin: 0 0 6px; color: var(--ink); text-transform: none; letter-spacing: -0.01em; font-size: 1.05em; }
.card p { margin: 0; font-size: 0.88em; }
.stat { margin: 0 0 18px; }
.stat .big { font-size: 3.5em; font-weight: 800; color: var(--brand); line-height: 1; }
.stat .label { font-size: 0.85em; color: var(--muted); margin-top: 4px; }
.steps { counter-reset: s; display: flex; flex-direction: column; gap: 10px; }
.step { counter-increment: s; display: flex; gap: 14px; align-items: flex-start; }
.step::before { content: counter(s, decimal-leading-zero); font-weight: 800; color: var(--brand); font-size: 1.4em; min-width: 40px; }
.step-content strong { display: block; margin-bottom: 2px; }
.step-content span { color: var(--muted); font-size: 0.88em; }
.pill { display: inline-block; background: #e0f2fe; color: var(--brand); padding: 2px 10px; border-radius: 999px; font-size: 0.78em; font-weight: 500; margin: 2px 2px; }
.pill.green { background: #dcfce7; color: var(--success); }
.pill.red { background: #fee2e2; color: var(--danger); }
.pill.orange { background: #fff7ed; color: var(--warn); }
.pill.gray { background: #f1f5f9; color: var(--muted); }
.split { display: grid; grid-template-columns: 1fr 1fr; gap: 28px; }
.split.right-wide { grid-template-columns: 0.9fr 1.1fr; }
.two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
table { width: 100%; border-collapse: collapse; font-size: 0.78em; margin: 8px 0; }
th { background: transparent; color: var(--ink); padding: 8px 10px; text-align: left; font-weight: 700; border-bottom: 2px solid var(--ink); }
td { padding: 6px 10px; border-bottom: 1px solid #e2e8f0; }
blockquote { border-left: 3px solid var(--accent); background: transparent; padding: 2px 0 2px 14px; margin: 12px 0; font-size: 0.88em; color: var(--muted); }
blockquote strong { color: var(--ink); }
section.closing { background: var(--ink); color: #fff; padding: 80px 90px; }
section.closing::before { display: none; }
section.closing h1 { color: #fff; font-size: 2.8em; line-height: 1.1; }
section.closing h2 { color: rgba(255,255,255,0.5); font-size: 0.75em; letter-spacing: 0.1em; text-transform: uppercase; }
img { display: block; margin: 0 auto; border-radius: 4px; }
strong { color: var(--ink); font-weight: 700; }
Editorial slide patterns
Title (lead):
<!-- _class: lead -->
<!-- _paginate: false -->
<div class="tag">Architecture Brief · Apr 2026</div>
# Big bold<br>title.
## One-line subtitle in muted grey
### author · context
Chapter divider:
<!-- _class: chapter -->
<div class="num">01</div>
# Chapter Title.
One-line description of this chapter.
Cards grid:
# Three Approaches
<div class="cards">
<div class="card">
<div class="card-num">OPTION 01</div>
<h3>Card title</h3>
<p>Short description of this option.</p>
<p style="margin-top:8px"><span class="pill">Tag</span> <span class="pill green">GA</span></p>
</div>
<div class="card teal"> ... </div>
<div class="card red"> ... </div>
</div>
Big-number stats:
<div class="stat">
<div class="big">3</div>
<div class="label">pillars of network defense</div>
</div>
Numbered steps:
<div class="steps">
<div class="step"><div class="step-content"><strong>Short title</strong><span>Detail line in muted grey</span></div></div>
<div class="step"><div class="step-content"><strong>Next step</strong><span>More detail</span></div></div>
</div>
Closing slide:
<!-- _class: closing -->
<!-- _paginate: false -->
## Takeaways
# Big<br>closing<br>statement.
<p>A short paragraph summarising the message.</p>
Avoiding overflow in Marp (editorial)
Marp slides are 1280×720. With top/bottom chrome and chapter-style padding the usable area is ~600px tall. Diagrams that overflow are the most common visual defect.
Image sizing rules — editorial:
| Diagram shape | Max width | Notes |
|---|
Wide flowchart LR | w:1050 | Good for end-to-end flows |
| Square / balanced | w:880 to w:960 | DNS, Zero Trust, decision trees |
Tall flowchart TB | w:820 max | Tall diagrams need narrower width to stay vertically short |
Minimize surrounding text on slides with a big diagram. Drop the ## subtitle when the image is the message — a # title plus the image is often enough. Keep any explanation to one short paragraph below (≤ 2 lines).
Slide Design Best Practices
- Target 20–25 content slides (excluding dividers and title/closing) for a 30-minute talk
- One idea per slide — avoid overcrowding
- Prefer visuals over prose. If a bullet list would work, a diagram, cards grid, or stats block usually works better.
- Tables: keep to 5–6 rows max; use
font-size: 0.78em in theme for compact rendering
- Diagrams: place on the right (
bg right:45%) with text on the left, or centered for full-width. In editorial style, full-width and slightly narrower (see rules above).
- Blockquotes render as callout boxes (standard) or inline editorial notes (editorial). Use for best practices, warnings, key takeaways.
- No emoji in headings (rendering can be inconsistent)
- Section dividers between major topics help pace the presentation — in editorial style use chapter numerals.
- Bold text renders in the primary color — use sparingly for emphasis
- For Linux/macOS, replace
Segoe UI with Inter or DejaVu Sans in the theme CSS
