add marp skill and slide split plan

2025-12-14 19:17:20 +01:00
parent 6523c94fda
commit 660ef3426c
3 changed files with 517 additions and 0 deletions
@@ -0,0 +1,373 @@
+# 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)
@@ -0,0 +1,79 @@
+---
+name: marp
+description: Marp/Marpit documentation and slide creation guide. Use this skill when working with Marp presentations, slide syntax, themes, directives, or troubleshooting Marp-related issues.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# Marp/Marpit Skill
+
+## Purpose
+
+This skill provides comprehensive knowledge about Marp (Markdown Presentation Ecosystem) and its core engine Marpit. Use this when creating, editing, or troubleshooting Markdown-based slide presentations.
+
+## Documentation Sources
+
+When you need Marp information, fetch from these official sources:
+
+### Marpit Framework (Core Engine)
+- **Main docs**: https://marpit.marp.app/
+- **Markdown syntax**: https://marpit.marp.app/markdown
+- **Directives**: https://marpit.marp.app/directives
+- **Theme CSS**: https://marpit.marp.app/theme-css
+- **Fragmented list**: https://marpit.marp.app/fragmented-list
+- **Image syntax**: https://marpit.marp.app/image-syntax
+
+### Marp CLI
+- **Usage guide**: https://github.com/marp-team/marp-cli
+
+## Key Concepts to Learn
+
+### 1. Slide Separation
+Slides are separated by `---` (horizontal rule). The first `---` after frontmatter starts the first slide.
+
+### 2. Directives
+- **Global directives**: Apply to all slides (in frontmatter)
+- **Local directives**: Apply to current slide only (`<!-- _directive: value -->`)
+- **Spot directives**: Underscore prefix for local scope
+
+### 3. Image Syntax
+Marp extends standard Markdown image syntax:
+- `![bg](image.jpg)` - background image
+- `![bg fit](image.jpg)` - fit to slide
+- `![bg right:40%](image.jpg)` - split background
+- `![w:200](image.jpg)` - width filter
+- `![h:300](image.jpg)` - height filter
+
+### 4. Theme CSS
+- Themes use CSS with special Marpit selectors
+- `section` = slide container
+- `section::after` = pagination
+- CSS variables for theming
+
+### 5. Scoped Styles
+```html
+<style scoped>
+/* Only applies to this slide */
+</style>
+```
+
+## Workflow
+
+When asked about Marp:
+
+1. **Read REFERENCE.md first** - Contains comprehensive syntax documentation
+2. **Check local files** - Read existing slides and themes in the project
+3. **Fetch official docs if needed** - Use WebFetch for edge cases
+4. **Provide concrete examples** - Show actual Marp syntax
+5. **Reference project conventions** - Follow CLAUDE.md guidelines
+
+## Project-Specific Notes
+
+This project uses:
+- Theme: `gaia`
+- Assets path: `./assets/`
+- Build output: `build/`
+- Dev server: `make dev` (port 1312)