--- name: marp description: "Use when asked to create a presentation, make slides, build a deck, or convert markdown to PDF/PPTX/HTML. Builds slide decks from Markdown with Marp (themes, custom CSS, speaker notes, directives, KaTeX)." --- # Marp — Markdown Presentation Ecosystem Marp converts Markdown into professional HTML, PDF, PPTX, and image slides via [Marp CLI](https://github.com/marp-team/marp-cli). No proprietary formats, no GUI. --- ## When to Activate - "create a presentation", "make slides", "build a deck", "pitch deck" - "convert markdown to slides", "markdown to PDF" - "speaker notes", "presenter notes in slides" - "set up Marp", "Marp theme", "Marp project" - Any task where the output is a `.pptx`, `.pdf`, or HTML slide deck --- ## Workflow ### Step 1 — Ensure Marp CLI Is Installed ```bash which marp || npx @marp-team/marp-cli@latest --version ``` If not present, install it: ```bash npm install --save-dev @marp-team/marp-cli # project npm install -g @marp-team/marp-cli # global ``` Or run via `npx` (no install required): ```bash npx @marp-team/marp-cli@latest [command] ``` --- ### Step 2 — Create or Review the Markdown Source Create `slides.md` (or any `.md` file). Key conventions: ```markdown --- marp: true theme: default paginate: true --- # Slide 1 Title Content here. --- # Slide 2 Title - Bullet point - Another point --- ## Even-Level Headings Start New Slides (H2 = new slide) ### H3 is a Section Label (no slide break) ``` #### Core Front Matter Options ```yaml --- marp: true # enable Marp processing theme: default # built-in: default, gaia, uncover paginate: true # show page numbers backgroundColor: #1e1e1e # dark background header: "Title" # persistent header footer: "© 2026" # persistent footer --- # Or override per-slide with directives: ``` #### Slide Separators | Syntax | Effect | |--------|--------| | `---` on its own line | Hard slide break | | `--` on its own line | Soft break (same section) | | `` | Auto-fit text to slide | #### Speaker Notes ```markdown ``` #### Charts & Code (Marp Core Features) ````markdown ```chart type: bar data: labels: [Q1, Q2, Q3, Q4] datasets: - label: Revenue data: [12, 19, 15, 28] ``` {type=bar} ``` ```` --- ### Step 3 — Choose Output Format & Run ```bash # HTML (default, opens in browser) marp slides.md # PDF (requires Chrome/Edge/Firefox) marp slides.md --pdf # PowerPoint marp slides.md --pptx # PNG images (one per slide) marp slides.md --images png # JPEG images marp slides.md --images jpeg # Output to specific path marp slides.md -o dist/slides.html # Watch mode (auto-reconvert on save) marp slides.md -w # HTTP server (on-demand conversion, ?pdf, ?pptx, ?png in query string) marp slides.md -s PORT=8080 marp slides.md -s # Preview window (desktop only) marp slides.md -p # Batch: entire directory marp --input-dir ./slides/ -o ./dist/ ``` #### Useful Flags ```bash --pdf-notes # include speaker notes in PDF --pdf-outlines # add PDF bookmarks --pptx-editable # editable PPTX (requires LibreOffice) --image-scale 2 # scale factor for image export --allow-local-files # embed local images (HTML only) --browser chrome # force specific browser for PDF/image export ``` --- ### Step 4 — Verify Output - **HTML**: open the `.html` file in a browser, test keyboard navigation (arrows, Space) - **PDF**: open and check pagination, fonts, image quality - **PPTX**: open in PowerPoint/Keynote/Google Slides - **Images**: check resolution, especially for `--image-scale 2` --- ### Step 5 — Automation (Optional) For CI/CD or project integration: ```json // package.json scripts { "scripts": { "slides:html": "marp src/slides.md -o public/slides.html", "slides:pdf": "marp src/slides.md --pdf", "slides:watch": "marp src/slides.md -w" } } ``` Or use the `--server` mode to serve presentations from a docs site: ```bash PORT=4321 marp docs/slides/ -s # Access at http://localhost:4321/slides.md?pdf ``` --- ## Marp Core Built-in Themes | Theme | Best For | |-------|----------| | `default` | Clean, minimal, all-purpose | | `gaia` | Modern with a sidebar, section headers | | `uncover` | Full-bleed image backgrounds | | Custom theme | CSS custom properties — see `marp-core` docs | ### Customizing Themes Override via `style` block or custom CSS: ```markdown --- marp: true style: | section { background: #0d1117; color: #e6edf3; font-family: 'Inter', sans-serif; } h1 { color: #58a6ff; } footer { color: #8b949e; } --- ``` --- ## Project Structure Recommendation ``` project/ ├── slides/ │ ├── cover.md # Title slide │ ├── agenda.md # Overview │ ├── content-1.md # Section 1 │ ├── content-2.md # Section 2 │ └── qa.md # Closing slide ├── src/ │ └── presentation.md # Combined deck (use !include directives) ├── public/ │ └── presentation.html └── dist/ ├── presentation.pdf └── presentation.pptx ``` Combine multiple files: ```markdown ``` --- ## Troubleshooting | Problem | Fix | |---------|-----| | "marp: command not found" | Use `npx @marp-team/marp-cli@latest` or install globally | | PDF export fails | Install Chrome/Edge/Firefox; use `--browser chrome` | | Images not found | Use absolute paths or `--allow-local-files` for HTML | | PPTX not editable | Re-export with `--pptx-editable` (requires LibreOffice) | | Fonts look wrong | Bundle fonts or use web-safe fonts in CSS | | Server mode 404 | Ensure `index.md` or `slides.md` exists in served dir | --- ## Key Marpit/Marp Markdown Extensions | Extension | Example | |-----------|---------| | Directives (global) | `` | | Directives (per-slide) | `` | | Built-in filters | ``, `` | | Code blocks | Fenced code with language and Marp extensions | | Charts (core) | `` ```chart `` blocks | | Math | `` ```math `` blocks via KaTeX | --- ## See also - `deck-narrative` — co-load for the deck's ARGUMENT (action titles, Minto top-down sequencing, one-message-per-slide, table-vs-chart selection, decision-slide construction) before Marp lays out the visuals. If exporting `--pptx`, run `deck-narrative/scripts/audit_deck.py` on the output before shipping — it mechanically catches system-font leaks (Rule 9) and other file-level defects a rendered preview can't show.