223015b/.claude/skills/marp/REFERENCE.md

Marp/Marpit Complete Reference

Overview

Marp = Markdown Presentation Ecosystem Marpit = The core framework ("skinny framework for creating slide deck from Markdown")

Built-in themes: default, gaia, uncover

---

Slide Structure

Slide Separation

Slides are separated by horizontal rulers:

---

Alternatives: ___, ***, - - -

Important: May need empty line before --- per CommonMark spec.

Basic Document Structure

---
marp: true
theme: gaia
paginate: true
---

# First Slide

Content here

---

# Second Slide

More content

<!-- Speaker notes go here -->

---

Directives

Syntax Options

HTML Comments:

<!-- theme: default -->
<!-- paginate: true -->

Front-matter (YAML):

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

Directive Scopes

Scope	Applies to	Syntax
Global	Entire deck	Normal directive
Local	Current + following slides	Normal directive mid-document
Spot	Single slide only	Underscore prefix: _directive

Global Directives

• theme — Slide deck theme
• style — Custom CSS
• lang — Language attribute (accessibility)
• headingDivider — Auto-split at heading levels (1-6)

Local Directives

• paginate — Page numbers (true/false/hold/skip)
• header — Persistent header text
• footer — Persistent footer text
• class — CSS class for slide
• backgroundColor — Slide background color
• backgroundImage — Background image URL
• backgroundPosition — CSS background-position
• backgroundRepeat — CSS background-repeat
• backgroundSize — CSS background-size
• color — Text color

Spot Directive Example

<!-- _backgroundColor: aqua -->
<!-- _class: lead -->

Only affects current slide.

Pagination Values

• true — Show and increment
• false — Hide but increment
• hold — Show without incrementing
• skip — Hide without incrementing

Heading Divider

---
headingDivider: 2
---

# Section 1
Content

## Slide 1.1    <!-- auto slide break -->
Content

## Slide 1.2    <!-- auto slide break -->
Content

---

Image Syntax

Basic Resizing

![w:200](image.jpg)           <!-- width 200px -->
![h:300](image.jpg)           <!-- height 300px -->
![w:200 h:150](image.jpg)     <!-- both -->

Units: px, em, cm, pt, etc. (no viewport units vw/vh)

Image Filters

![blur:10px](image.jpg)
![brightness:1.5](image.jpg)
![contrast:200%](image.jpg)
![grayscale:1](image.jpg)
![sepia:50%](image.jpg)
![hue-rotate:180deg](image.jpg)
![invert:100%](image.jpg)
![opacity:0.5](image.jpg)
![saturate:2](image.jpg)
![drop-shadow:0,5px,10px,rgba(0,0,0,.4)](image.jpg)

Combine multiple:

![brightness:.8 sepia:50%](image.jpg)

Background Images

![bg](image.jpg)              <!-- full background -->
![bg fit](image.jpg)          <!-- contain/fit -->
![bg cover](image.jpg)        <!-- cover (default) -->
![bg auto](image.jpg)         <!-- original size -->
![bg 150%](image.jpg)         <!-- scale percentage -->

Split Backgrounds

![bg left](image.jpg)         <!-- left half -->
![bg right](image.jpg)        <!-- right half -->
![bg left:40%](image.jpg)     <!-- custom split -->
![bg right:33%](image.jpg)

Multiple Backgrounds

![bg](image1.jpg)
![bg](image2.jpg)
![bg](image3.jpg)

Arranges horizontally by default.

![bg vertical](image1.jpg)
![bg](image2.jpg)

Arranges vertically.

---

Fragmented Lists (Animations)

Bullet Lists — Use *

* First item      <!-- reveals first -->
* Second item     <!-- reveals second -->
* Third item      <!-- reveals third -->

Regular - or + bullets don't animate.

Ordered Lists — Use )

1) First item
2) Second item
3) Third item

Regular . numbered lists don't animate.

Output

<li data-marpit-fragment="1">First</li>
<li data-marpit-fragment="2">Second</li>

Note: Actual animation depends on presentation viewer.

---

Theme CSS

Required Metadata

/* @theme my-theme */

Core Selectors

/* Slide container */
section {
  width: 1280px;
  height: 720px;
  font-size: 32px;
}

/* Higher specificity alternative */
:root {
  --color-primary: #3498db;
}

/* Pagination */
section::after {
  content: attr(data-marpit-pagination) ' / ' attr(data-marpit-pagination-total);
}

Scoped Styles

<style scoped>
/* Only this slide */
h1 { color: red; }
</style>

Global Inline Styles

<style>
/* All slides */
section { background: #f0f0f0; }
</style>

Theme Inheritance

/* @theme derived-theme */
@import 'default';
/* or */
@import-theme 'default';

Units

• rem scales relative to slide <section> (isolated from HTML root)
• Slide dimensions require absolute units (px, cm, in, mm)

---

Marp CLI

Installation

npm install -g @marp-team/marp-cli
# or
brew install marp-cli

Basic Conversion

marp slide.md                    # → HTML
marp --pdf slide.md              # → PDF
marp --pptx slide.md             # → PowerPoint
marp --images png slide.md       # → PNG images

Development Server

marp --server ./slides/
PORT=1312 marp --server ./

Query formats: http://localhost:8080/deck.md?pdf

Watch Mode

marp --watch slide.md

Key Options

-o, --output <file>      # Output path
-w, --watch              # Watch for changes
-s, --server             # HTTP server mode
-p, --preview            # Open preview window
--pdf                    # PDF output
--pptx                   # PowerPoint output
--images [png|jpeg]      # Image output
--image-scale <n>        # Resolution (e.g., 2 for 2x)
--allow-local-files      # Enable local file access (security risk)
--pdf-notes              # Include speaker notes in PDF
--browser <name>         # chrome, edge, firefox

---

Common Patterns

Title Slide

<!-- _class: lead -->

# Presentation Title

**Author Name**
Date

Two-Column Layout (via background)

![bg left:50%](image.jpg)

# Right Content

Text appears on right side

Speaker Notes

# Slide Title

Content

<!--
These are speaker notes.
Not visible in slides.
Visible in presenter mode.
-->

Custom Class

<!-- _class: centered dark -->

# Centered Dark Slide

Then in CSS/theme:

section.centered { text-align: center; }
section.dark { background: #222; color: #fff; }

---

Project Conventions (This Project)

• Theme: gaia
• Assets: ./assets/filename.png
• Build output: build/
• Dev server: make dev (port 1312)
• Never end with --- (creates empty slide)