hdm/223015b
1
0
Fork 0
Code Pull Requests Activity

lecture-01 #1

Merged
libretech merged 25 commits from lecture-01 into main 2025-12-18 01:23:51 +01:00
Conversation 0 Commits 25 Files Changed 41
+517
3 changed files with 517 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 660ef3426c - Show all commits
.claude/skills/marp/REFERENCE.md
+373
View File
@@ -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)
.claude/skills/marp/SKILL.md
+79
View File
@@ -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)
PLAN-split-slides.md
+65
View File
@@ -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