| name | marp-skill |
| description | Skill for understanding and authoring Marp (Markdown + Marpit) presentations.
Provides syntax & semantics, links to authoritative docs, usage patterns, and
a small checklist to validate slide decks before export.
|
| scope | workspace |
Marp Skill
Summary
- Purpose: Help edit, validate, and generate Marp presentations written in Markdown.
- Scope: Workspace-scoped guidance and examples for
.md slide decks using Marp.
When to use this skill
- Convert notes to Marp slides.
- Add Marp front-matter, themes, or custom CSS.
- Validate slide separators, background directives, and image paths.
- Produce export commands for PDF/HTML using Marp CLI.
Quick Workflow (step-by-step)
- Ensure file front-matter contains
marp: true and desired global options (theme, paginate, size).
- Structure slides using horizontal separators (
---) for new slides and -- or ---- only when using alternate separators per theme.
- Apply per-slide directives via comments or attributes (e.g., background, style, class) as supported by Marp/Marpit.
- Preview locally with Marp preview extensions or render via Marp CLI to check exports.
- Export to PDF/HTML and verify page sizes, margins, and image DPI.
Decision points & branching
- Export target:
PDF → prefer CLI render (marp --pdf or npx @marp-team/marp-cli) for consistent pagination; HTML → export with --html or use GitHub Pages.
- Theme customization: Use built-in themes for quick work; add
style: blocks or external CSS for brand consistency.
- Advanced layout: If you need CSS grid/flex layouts, include scoped
<style> blocks but validate compatibility with Marp renderers.
Quality checklist / Completion criteria
- YAML front-matter exists and begins with
--- and marp: true.
- Slides separated by
--- where intended; no rogue separators inside code blocks.
- Images referenced with workspace-relative paths and present in repo.
- No unescaped HTML that could break renderers.
- Exports (PDF/HTML) render without missing assets and with expected slide count.
Useful references
Common snippets
YAML front-matter example:
marp: true
theme: default
paginate: true
size: 16:9
Slide separator:
Per-slide background example:
Notes and speaker notes (use Marp supported patterns or plugin-specific syntax depending on renderer).
Export example (CLI):
- Using npx:
npx @marp-team/marp-cli main.md --pdf -o main.pdf
- If
marp CLI is installed globally: marp main.md --pdf -o main.pdf
Suggested prompts to use this skill
- "Create a 10-slide Marp deck about X with title slide, section breaks, and conclusion."
- "Add a dark theme and center the title on the first slide using Marp front-matter."
- "Validate this Marp file for export to PDF and list issues."
- "Convert these notes into Marp slides using
--- separators and include speaker notes."
Converting from LaTeX
- Use Pandoc to produce Markdown from LaTeX (works well for
article/beamer sources). Example:
pandoc slides.tex -f beamer -t markdown -s -o slides.md --extract-media=images --wrap=none
- If your source is plain LaTeX (not Beamer), omit
-f beamer. --extract-media=images writes embedded/linked images into images/.
- Pandoc preserves math as LaTeX (inline
$...$ and display $$...$$). Keep those delimiters so Marp can render via KaTeX.
- After conversion:
- Add
marp: true and math: true (or enable KaTeX in your Marp renderer/settings) to YAML front-matter so equations render.
- Convert top-level
\\section/\\frame titles into slide headings and insert --- separators where logical slide breaks belong.
- Check image paths (pandoc's extracted media path may need adjusting to workspace-relative URLs).
- Complex macros, custom commands, and table/layout code usually require manual cleanup. Consider using Pandoc filters or
--lua-filter to expand macros where possible.
- Export tip: render and verify math/images with Marp CLI:
npx @marp-team/marp-cli slides.md --pdf -o slides.pdf --allow-local-files
- Quick checklist after conversion: math renders correctly, images load, slide count matches expected, and any custom macros are replaced or removed.
Ambiguities / Questions
- Should this skill be available workspace-wide or as a personal skill in your VS Code profile?
- Do you want sample theme files or a small template added to the repo alongside this skill?
Next actions
- I can add a
templates/ folder with a ready-to-use slides-template.md and a basic CSS theme.
- I can wire up example
tasks.json or simple CLI commands in the repo's README for quick exports.
Generated by the Marp skill generator. Update the references links or templates as needed.
