From 660ef3426c8bdba8ebc8c8c2c8d57dbb7bc9809b Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Sun, 14 Dec 2025 19:17:20 +0100 Subject: [PATCH] add marp skill and slide split plan --- .claude/skills/marp/REFERENCE.md | 373 +++++++++++++++++++++++++++++++ .claude/skills/marp/SKILL.md | 79 +++++++ PLAN-split-slides.md | 65 ++++++ 3 files changed, 517 insertions(+) create mode 100644 .claude/skills/marp/REFERENCE.md create mode 100644 .claude/skills/marp/SKILL.md create mode 100644 PLAN-split-slides.md diff --git a/.claude/skills/marp/REFERENCE.md b/.claude/skills/marp/REFERENCE.md new file mode 100644 index 0000000..5b9215a --- /dev/null +++ b/.claude/skills/marp/REFERENCE.md @@ -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 + + +``` + +--- + +## Directives + +### Syntax Options + +**HTML Comments:** +```markdown + + +``` + +**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 + + +``` +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 +Content + +## Slide 1.2 +Content +``` + +--- + +## Image Syntax + +### Basic Resizing +```markdown +![w:200](image.jpg) +![h:300](image.jpg) +![w:200 h:150](image.jpg) +``` + +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) +![bg fit](image.jpg) +![bg cover](image.jpg) +![bg auto](image.jpg) +![bg 150%](image.jpg) +``` + +### Split Backgrounds +```markdown +![bg left](image.jpg) +![bg right](image.jpg) +![bg left:40%](image.jpg) +![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 +* Second item +* Third item +``` + +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 +
  • First
    • +
  • Second
    • +``` + +**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 + +``` + +### Global Inline Styles +```markdown + +``` + +### Theme Inheritance +```css +/* @theme derived-theme */ +@import 'default'; +/* or */ +@import-theme 'default'; +``` + +### Units +- `rem` scales relative to slide `
    ` (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 # 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 # Resolution (e.g., 2 for 2x) +--allow-local-files # Enable local file access (security risk) +--pdf-notes # Include speaker notes in PDF +--browser # chrome, edge, firefox +``` + +--- + +## Common Patterns + +### Title Slide +```markdown + + +# 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 + + +``` + +### Custom Class +```markdown + + +# 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) diff --git a/.claude/skills/marp/SKILL.md b/.claude/skills/marp/SKILL.md new file mode 100644 index 0000000..3d9a9fe --- /dev/null +++ b/.claude/skills/marp/SKILL.md @@ -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 (``) +- **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 + +``` + +## 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) diff --git a/PLAN-split-slides.md b/PLAN-split-slides.md new file mode 100644 index 0000000..768556f --- /dev/null +++ b/PLAN-split-slides.md @@ -0,0 +1,65 @@ +# Plan: Split index.md into multiple files + +## Current state +- ~4200 lines, 5 sessions + intro/outro +- Shared: frontmatter, styles, intro slides (title, about, schedule, survey, overview) +- Per-session: actual content + +## Proposed structure + +``` +slides/ +├── _frontmatter.yml # shared marp config +├── _styles.md # shared CSS +├── _intro.md # title, about, schedule, survey, overview +├── termin-1.md # Session 1 content +├── termin-2.md # Session 2 content +├── termin-3.md # Session 3 content +├── termin-4.md # Session 4 content +├── termin-5.md # TBA session +└── _outro.md # Q&A, license +``` + +## Makefile targets + +```makefile +# Shared parts +HEADER = slides/_frontmatter.yml slides/_styles.md +INTRO = slides/_intro.md +OUTRO = slides/_outro.md + +# Build single termin (intro + content + outro) +build-termin-%: + cat $(HEADER) $(INTRO) slides/termin-$*.md $(OUTRO) > build/termin-$*.md + marp build/termin-$*.md -o build/termin-$*.html + +# Dev mode for single termin +dev-%: + cat $(HEADER) $(INTRO) slides/termin-$*.md $(OUTRO) > build/.dev.md + PORT=1312 marp --server build/ + +# Build all +build-all: + cat $(HEADER) $(INTRO) slides/termin-*.md $(OUTRO) > build/all.md + marp build/all.md -o build/all.html +``` + +## Usage + +```bash +make dev-1 # preview termin 1 +make dev-3 # preview termin 3 +make build-termin-2 # build termin 2 +make build-all # build everything +``` + +## Trade-offs +- Requires intermediate file generation +- Can't use `marp --watch` directly on source (need wrapper) +- But: clean separation, single source of truth for styles + +## Status +- [ ] Learn Marp/Marpit in depth first +- [ ] Implement split +- [ ] Update Makefile +- [ ] Test all targets