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:
```markdown
---
```
Alternatives: `___`, `***`, `- - -`

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

### Basic Document Structure
```markdown
---
marp: true
theme: gaia
paginate: true
---

# First Slide

Content here

---

# Second Slide

More content

<!-- Speaker notes go here -->
```

---

## Directives

### Syntax Options

**HTML Comments:**
```markdown
<!-- theme: default -->
<!-- paginate: true -->
```

**Front-matter (YAML):**
```markdown
---
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
```markdown
<!-- _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
```markdown
---
headingDivider: 2
---

# Section 1
Content

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

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

---

## Image Syntax

### Basic Resizing
```markdown
![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
```markdown
![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:
```markdown
![brightness:.8 sepia:50%](image.jpg)
```

### Background Images
```markdown
![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
```markdown
![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
```markdown
![bg](image1.jpg)
![bg](image2.jpg)
![bg](image3.jpg)
```
Arranges horizontally by default.

```markdown
![bg vertical](image1.jpg)
![bg](image2.jpg)
```
Arranges vertically.

---

## Fragmented Lists (Animations)

### Bullet Lists — Use `*`
```markdown
* First item      <!-- reveals first -->
* Second item     <!-- reveals second -->
* Third item      <!-- reveals third -->
```

Regular `-` or `+` bullets don't animate.

### Ordered Lists — Use `)`
```markdown
1) First item
2) Second item
3) Third item
```

Regular `.` numbered lists don't animate.

### Output
```html
<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
```css
/* @theme my-theme */
```

### Core Selectors
```css
/* 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
```markdown
<style scoped>
/* Only this slide */
h1 { color: red; }
</style>
```

### Global Inline Styles
```markdown
<style>
/* All slides */
section { background: #f0f0f0; }
</style>
```

### Theme Inheritance
```css
/* @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
```bash
npm install -g @marp-team/marp-cli
# or
brew install marp-cli
```

### Basic Conversion
```bash
marp slide.md                    # → HTML
marp --pdf slide.md              # → PDF
marp --pptx slide.md             # → PowerPoint
marp --images png slide.md       # → PNG images
```

### Development Server
```bash
marp --server ./slides/
PORT=1312 marp --server ./
```

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

### Watch Mode
```bash
marp --watch slide.md
```

### Key Options
```bash
-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
```markdown
<!-- _class: lead -->

# Presentation Title

**Author Name**
Date
```

### Two-Column Layout (via background)
```markdown
![bg left:50%](image.jpg)

# Right Content

Text appears on right side
```

### Speaker Notes
```markdown
# Slide Title

Content

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

### Custom Class
```markdown
<!-- _class: centered dark -->

# Centered Dark Slide
```

Then in CSS/theme:
```css
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)