marp-slides · diff
v1.1.0 to v1.2.0
225 added, 79 removed. Audit A to A.
---
name: marp-slides
- description: Create, edit, review, and export polished Marp Markdown slide decks in Canvas Notebook. Use when the user wants Markdown-based presentations, `.marp.md` or `.slides.md` files, fast version-controlled decks, Marp PDF/image/PPTX export, speaker notes, presentation outlines, or better looking slides that should stay close to plain text.
+ description: Create, edit, review, preview, and export polished Marp Markdown slide decks in Canvas Notebook. Use when the user wants Markdown-native presentations, `.marp.md` or `.slides.md` files, version-controlled decks, Marp PDF/image/PPTX/HTML export, speaker notes, dashboard-style slides, data cards, or better looking decks that should remain close to plain text.
license: "MIT"
metadata:
- version: "1.1.0"
+ version: "1.2.0"
+ upstream_reference: "https://github.com/robonuggets/marp-slides"
+ adapted_for: "Canvas Notebook"
---
# Marp Slides
- Create presentation decks as Marp Markdown files that Canvas Notebook can preview
- and export. Use this skill when a Markdown-native deck is better than directly
- authoring PowerPoint, Google Slides, or a custom HTML presentation.
+ Create presentation decks as Marp Markdown files that Canvas Notebook can
+ preview and export. Use this skill when a Markdown-native deck is better than
+ directly authoring PowerPoint, Google Slides, or a custom HTML presentation.
- ## Output Contract
+ ## Canvas Output Contract
- - Prefer a workspace file ending in `.marp.md` or `.slides.md`.
- - Include `marp: true` in YAML frontmatter so Canvas enables the slide preview.
- - Use `---` to separate slides after the frontmatter block.
- - Keep the deck source readable and version-control friendly. Avoid dense raw
- HTML unless Markdown cannot express the layout.
- - Use relative image paths for local workspace assets. Canvas inlines supported
- workspace images for preview and export.
- - Return the final deck path and mention intended export format only if relevant.
+ - Create or update a workspace file ending in `.marp.md` or `.slides.md`.
+ - Put valid YAML frontmatter at the very top of the file.
+ - Include `marp: true` in frontmatter; Canvas also detects `.marp.md` and
+ `.slides.md` file names.
+ - Use plain `---` slide separators after frontmatter.
+ - Keep the source readable and easy to diff. Use HTML/CSS only when Markdown is
+ not expressive enough.
+ - Use relative paths for local workspace images such as `./images/chart.png`.
+ Canvas inlines supported workspace assets for preview/export when possible.
+ - Avoid absolute filesystem paths. They are brittle and may not resolve in the
+ preview/export sandbox.
+ - Return the final deck path and mention export options only when relevant.
## Canvas Workflow
- 1. Decide whether Marp is the right output:
- - Use Marp for text-first decks, technical talks, client narratives, reports,
- training, pitch drafts, and decks that should be easy to diff and revise.
- - Use the `pptx` skill when the user needs fully editable PowerPoint-native
- objects, corporate templates, or heavy manual editing in PowerPoint.
+ 1. Decide whether Marp is the right target:
+ - Use Marp for text-first decks, technical talks, client narratives,
+ dashboards, reports, trainings, pitch drafts, and decks that should be
+ easy to revise in Git.
+ - Use the `pptx` skill when the user needs editable PowerPoint-native
+ shapes, corporate templates, or heavy manual editing in PowerPoint.
- Use `frontend-slides` when the user needs a standalone animated web
- presentation with custom interaction.
- 2. Create or update a `.marp.md` / `.slides.md` file.
- 3. Start with a compact slide outline before writing full slide copy.
- 4. Define the visual system in frontmatter and one `<style>` block near the top.
- 5. Keep every slide within a 16:9 viewport. Split overloaded content.
- 6. If export is requested, use the Canvas UI export actions or the existing Marp
- export endpoints; do not hand-roll a converter.
+ presentation or custom runtime interaction.
+ 2. Draft a compact outline before writing full slide copy.
+ 3. Choose a concrete visual direction: executive memo, data dashboard,
+ editorial report, workshop, classroom teaching, product launch, or investor
+ brief.
+ 4. Build the deck as a `.marp.md` / `.slides.md` file with frontmatter and a
+ single `<style>` block near the top.
+ 5. Keep every slide within a 16:9 viewport. Split overloaded slides instead of
+ shrinking text.
+ 6. Preview in Canvas and revise spacing, contrast, and overflow before final
+ delivery.
+ 7. Use Canvas Marp export actions/endpoints for PDF, images, PPTX, or HTML.
+ Do not hand-roll a converter.
- ## Required Deck Skeleton
+ ## Canvas-Safe HTML And CSS
- Use this as the baseline and adapt the theme to the user's brand, audience, and
- content.
+ Canvas allows common HTML layout tags, inline styles, tables, images, details,
+ summary, progress, abbr, and text formatting inside Marp. It does not allow
+ arbitrary raw SVG elements in user-authored Markdown. Marp itself renders slides
+ to SVG internally, but custom `<svg>` charts in Markdown may be sanitized.
+ Prefer Canvas-safe components:
+
+ - metric cards built from `<div>`, `<span>`, and CSS
+ - tables styled as compact scorecards
+ - CSS bar charts using flex rows and percentage widths
+ - progress bars with `<progress>`
+ - gauges or donuts as CSS `conic-gradient` blocks
+ - browser, terminal, chat, and timeline mockups made from HTML/CSS
+ - icons as text labels, emoji only if the deck tone allows it, or local images
+
+ If a requested chart truly needs SVG precision, create it as a local image asset
+ first, reference it with a relative path, then preview/export the deck.
+
+ ## Required Starter Skeleton
+
+ Adapt this baseline to the user's brand, audience, and content.
+
```markdown
---
marp: true
theme: default
paginate: true
size: 16:9
title: "Presentation title"
description: "Short deck summary"
---
<style>
+ :root {
+ --accent: #2563eb;
+ --ink: #111827;
+ --muted: #64748b;
+ --bg: #f8fafc;
+ --panel: #ffffff;
+ --line: #e5e7eb;
+ }
+
section {
font-family: "Aptos", "Helvetica Neue", Arial, sans-serif;
- color: #111827;
- background: #f8fafc;
- padding: 56px;
+ color: var(--ink);
+ background: var(--bg);
+ padding: 56px 64px;
}
+
section.lead {
display: flex;
flex-direction: column;
justify-content: center;
}
+
h1 {
font-size: 54px;
line-height: 1.02;
}
+
h2 {
font-size: 34px;
+ line-height: 1.12;
}
+
p,
li {
- font-size: 24px;
+ font-size: 23px;
line-height: 1.35;
}
+
strong {
- color: #2563eb;
+ color: var(--accent);
}
- footer {
- color: #64748b;
+
+ .kicker {
+ color: var(--accent);
+ font-size: 15px;
+ font-weight: 700;
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
}
+
+ .grid {
+ display: grid;
+ grid-template-columns: repeat(3, 1fr);
+ gap: 18px;
+ }
+
+ .card {
+ background: var(--panel);
+ border: 1px solid var(--line);
+ border-radius: 12px;
+ padding: 20px;
+ }
+
+ .metric {
+ font-size: 40px;
+ font-weight: 800;
+ }
+
+ .muted {
+ color: var(--muted);
+ }
</style>
<!-- _class: lead -->
<!-- _paginate: false -->
+ <div class="kicker">Context label</div>
+
# Presentation title
Short, specific promise for the audience.
---
## The point of this deck
- One clear idea per bullet.
- Keep bullets short.
- Split crowded slides.
```
- ## Slide Design Rules
+ ## Visual Directions
- - Title slide: one title, one subtitle, optional context line.
- - Content slide: one idea, up to four bullets or two short paragraphs.
- - Section divider: one section title and one sentence of orientation.
- - Data slide: state the takeaway in the title; include units and source notes.
- - Code slide: show only the lines that matter, usually no more than 12.
- - Image slide: use the image as a real layout element, not decoration.
- - Closing slide: summarize the decision, next step, or call to action.
+ Pick one direction and keep it consistent across the deck.
- Avoid generic decks. Pick a concrete visual direction: editorial report,
- technical briefing, investor memo, product launch, workshop, or classroom
- teaching. Match typography, spacing, color, and image treatment to that context.
+ - Executive memo: quiet light theme, strong hierarchy, few colors, concise
+ claims, tables and decision boxes.
+ - Data dashboard: dark or neutral theme, metric cards, trend rows, CSS bars,
+ compact footnotes, clear units.
+ - Editorial report: large title type, generous whitespace, one strong image per
+ section, pull quotes.
+ - Product launch: hero slides, comparison cards, capability rows, screenshots
+ as real content.
+ - Workshop/training: section dividers, step cards, examples, recap slides.
+ - Investor brief: thesis title, market proof, risk table, milestones, ask.
- ## Marp Syntax Patterns
+ Avoid generic one-note decks. Match typography, spacing, color, and image
+ treatment to the audience and subject matter.
- Use global directives in frontmatter:
+ ## Component Patterns
- ```yaml
- ---
- marp: true
- theme: default
- paginate: true
- size: 16:9
- ---
+ ### Metric Card
+
+ ```html
+ <div class="card">
+ <div class="muted">Qualified pipeline</div>
+ <div class="metric">$4.2M</div>
+ <div style="color:#16a34a;">+18% vs last quarter</div>
+ </div>
```
- Use local scoped directives for one slide:
+ ### CSS Bar Chart
- ```markdown
- ---
+ ```html
+ <div class="card">
+ <div style="display:flex; justify-content:space-between;">
+ <span>Enterprise</span><strong>72%</strong>
+ </div>
+ <div style="height:10px; background:#e5e7eb; border-radius:999px; overflow:hidden;">
+ <div style="width:72%; height:100%; background:var(--accent);"></div>
+ </div>
+ </div>
+ ```
- <!-- _class: lead -->
- <!-- _paginate: false -->
+ ### CSS Donut / Gauge
- # Section title
+ ```html
+ <div style="width:140px; height:140px; border-radius:50%;
+ background:conic-gradient(var(--accent) 0 76%, #e5e7eb 76% 100%);
+ display:grid; place-items:center;">
+ <div style="width:88px; height:88px; border-radius:50%; background:var(--panel);
+ display:grid; place-items:center; font-weight:800;">76%</div>
+ </div>
```
- Use split image backgrounds for polished layouts:
+ ### Status Row
- ```markdown
- ---
+ ```html
+ <div class="card" style="display:flex; align-items:center; justify-content:space-between;">
+ <span><span style="color:#16a34a;">●</span> CRM enrichment</span>
+ <strong>Ready</strong>
+ </div>
+ ```
- 
+ ### Terminal Mockup
- ## What changed
+ ```html
+ <div style="background:#0f172a; color:#dbeafe; border-radius:12px; padding:18px;
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size:18px;">
+ <div style="color:#93c5fd;">$ canvas export deck.marp.md --pdf</div>
+ <div>Rendered 14 slides in 3.2s</div>
+ </div>
+ ```
- - Faster workflow
- - Clearer status
- - Fewer manual steps
+ ### Details And Tooltips
+
+ Use sparingly; they work best in HTML preview and may not be meaningful in PDF.
+
+ ```html
+ <details>
+ <summary>Assumption details</summary>
+ <p>Pipeline excludes renewal-only accounts.</p>
+ </details>
+
+ <abbr title="Customer acquisition cost">CAC</abbr>
```
- Use presenter notes only in HTML comments that are not directives:
+ ## Image Rules
+ - Prefer local workspace images when the deck must export reliably.
+ - Use `` for split slides.
+ - Use `` for full-bleed image slides.
+ - Hide headers or page numbers on visual slides with local directives:
+ `<!-- _header: "" -->` or `<!-- _paginate: false -->`.
+ - Do not use decorative stock-like images when the user needs product, data, or
+ workflow clarity.
+ - Remote `https:` images can work in preview, but local copies are safer for
+ repeatable export.
+
+ ## Data And Chart Rules
+
+ - Put the takeaway in the slide title.
+ - Include units, time range, and source notes when data is shown.
+ - Prefer simple visual encodings over dense tables.
+ - Do not fake precision. Round numbers unless exact values matter.
+ - For multi-series data, use one accent color plus neutral supporting colors.
+ - If a chart is too complex for CSS/HTML, generate or save it as an image and
+ embed it with a relative path.
+
+ ## Speaker Notes
+
+ Use normal HTML comments for presenter notes. Do not confuse them with Marp
+ directives.
+
```markdown
<!--
- Presenter note: pause here and show the live example.
+ Presenter note: pause here and ask which risk matters most to the team.
-->
```
+ ## Export Guidance
+
+ Canvas Notebook provides Marp preview and export actions for Marp Markdown
+ files. Normal Marp PPTX export is visually faithful, but it is not guaranteed to
+ produce fully editable native PowerPoint objects. Use `pptx` instead when the
+ user requires PowerPoint-native editability.
+
+ HTML export preserves more interactive behavior than PDF/PPTX. PDF/images are
+ best for sharing fixed-layout decks.
+
## Quality Checks
- - The file name or frontmatter triggers Marp preview in Canvas.
- - Frontmatter is valid YAML and appears at the very top of the file.
+ - File name or frontmatter triggers Marp preview in Canvas.
+ - Frontmatter is valid YAML and appears at the top of the file.
- Slide separators are plain `---` lines.
- - No slide depends on internet-only assets unless the user requested that.
- - Text does not crowd the slide; split content rather than shrinking everything.
- - Contrast is readable and repeated elements are consistent.
- - Export limitations are clear: normal Marp PPTX export is visually faithful but
- not guaranteed to be fully editable as native PowerPoint objects.
+ - Slides fit 16:9 without clipped content.
+ - Text is readable at presentation distance.
+ - Contrast is high enough on every slide.
+ - Repeated elements use consistent placement and sizing.
+ - Local assets resolve with relative paths.
+ - PDF/PPTX/HTML export limitations are clear to the user.