add documentation

- README.md: project overview, commands, structure - CLAUDE.md: agent guidelines for slide editing
2025-12-30 11:30:45 +01:00
parent 41a6c8bd2a
commit 3c78c898dd
2 changed files with 256 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,74 @@
+# CLAUDE.md - Agent Guidelines for HdM Slides
+
+This project builds presentation decks for Marp, supporting multiple courses.
+
+## Courses
+
+- **223015b** - Dateiformate, Schnittstellen, Speichermedien (6 Termine)
+- **223015c** - Internettechnologien (3 Termine)
+
+## Agent Restrictions
+
+- Agent NEVER runs commands outside this folder
+- Agent NEVER runs build/deploy commands without explicit user request
+- Agent NEVER runs deploy commands (make deploy, scp, etc.) without explicit user permission
+
+## Critical File Protection
+
+Slide files in `courses/*/slides/*.md` are main content files:
+- ALLOWED: Adding slides, adjusting content, fixing typos, enhancing sections
+- FORBIDDEN (without permission): Deleting slides, removing sections, bulk deletions
+- Before ANY deletion: ALWAYS ask user for confirmation
+
+## Project Structure
+
+```
+courses/
+├── 223015b/slides/     # Dateiformate course
+└── 223015c/slides/     # Internettechnik course
+scripts/                # Shared scripts
+themes/                 # Custom Marp themes
+build/                  # Generated output (gitignored)
+```
+
+## Build Commands
+
+```bash
+make dev-b          # Dev server 223015b (port 1312)
+make dev-c          # Dev server 223015c (port 1313)
+make build          # Build all courses
+make build-b        # Build 223015b only
+make build-c        # Build 223015c only
+make html           # HTML only
+make pdf            # PDF only
+make deploy         # Deploy all (ASK FIRST!)
+```
+
+## Nix Flake Commands
+
+```bash
+nix develop                           # Dev shell with all tools
+nix run .#qr -- "https://example.com" # Generate QR code
+nix run .#qr-slides -- 223015b        # QR for course
+nix run .#optimize-img -- <path>      # Optimize images
+```
+
+## Code Style Guidelines
+
+### File Structure
+- Slides in `courses/<course>/slides/`
+- Assets in `courses/<course>/slides/assets/`
+- Always reference images as `./assets/filename.png`
+
+### Naming Conventions
+- Slide files: `YYYY-MM-DD-termin-N-topic.md`
+- Images: `snake_case.jpg` or `kebab-case.jpg`
+
+### Markdown Style
+- Use ATX-style headers (# ## ###)
+- Frontmatter for slide metadata
+- Never include a final `---` (creates empty slide)
+
+### Git Workflow
+- Commit messages: ALWAYS lowercase
+- NEVER add co-authoring lines or generated footers
--- a/README.md
+++ b/README.md
@@ -0,0 +1,182 @@
+# HdM Slides
+
+**Modul "Technik 1"** - 1. Semester - Digital- und Medienwirtschaft
+Hochschule der Medien Stuttgart - Wintersemester 2025/26
+
+---
+
+## Kurse
+
+### 223015b - Dateiformate, Schnittstellen, Speichermedien & Distributionswege
+
+| # | Datum | Thema |
+|---|-------|-------|
+| 0 | 19.12.2025 | Intro |
+| 1 | 19.12.2025 | Grundlagen, Text & Audio |
+| 2 | 09.01.2026 | Bild- & Videoformate |
+| 3 | 23.01.2026 | Speichermedien & Schnittstellen |
+| 4 | 30.01.2026 | Distribution, APIs & Zukunft |
+| 5 | TBA | Vertiefung & offene Fragen |
+
+### 223015c - Internettechnologien
+
+| # | Datum | Thema |
+|---|-------|-------|
+| 1 | 20.12.2025 | Geschichte, Grundlagen & HTML |
+| 2 | 10.01.2026 | Netzwerke, Protokolle & CSS |
+| 3 | 24.01.2026 | Interaktivitat & JavaScript |
+
+**Dozent:** Michael Czechowski - mail@librete.ch
+
+---
+
+## Quick Start
+
+### Mit Nix (empfohlen)
+
+```bash
+# Development shell mit allen Tools
+nix develop
+
+# Oder direkt QR-Code generieren
+nix run .#qr -- "https://example.com"
+nix run .#qr-slides -- 223015b
+```
+
+### Ohne Nix
+
+```bash
+npm install
+make dev-b   # 223015b auf Port 1312
+make dev-c   # 223015c auf Port 1313
+```
+
+---
+
+## Development
+
+### Dev Server starten
+
+```bash
+make dev-b   # 223015b (Dateiformate) - http://localhost:1312
+make dev-c   # 223015c (Internettechnik) - http://localhost:1313
+```
+
+### Build
+
+```bash
+make build      # Alle Kurse (HTML + PDF)
+make build-b    # Nur 223015b
+make build-c    # Nur 223015c
+make html       # Nur HTML
+make pdf        # Nur PDF
+```
+
+### Deploy
+
+```bash
+make deploy     # Alle Kurse
+make deploy-b   # Nur 223015b
+make deploy-c   # Nur 223015c
+```
+
+---
+
+## Tools
+
+### QR-Code Generator
+
+```bash
+# Mit Nix
+nix run .#qr -- "https://librete.ch/hdm/223015b/"
+nix run .#qr -- "https://example.com" output.png
+
+# Mit Make
+make qr URL=https://example.com
+make qr URL=https://example.com OUTPUT=my-qr.png
+
+# Fur Kurse
+make qr-slides COURSE=223015b
+```
+
+### Bilder optimieren
+
+```bash
+# Mit Nix
+nix run .#optimize-img -- courses/223015b/slides/assets/
+
+# Mit Make
+make optimize-images COURSE=223015b
+```
+
+---
+
+## Projektstruktur
+
+```
+hdm/
+├── courses/
+│   ├── 223015b/
+│   │   └── slides/
+│   │       ├── 2025-12-19-termin-1-grundlagen-text-audio.md
+│   │       ├── assets/
+│   │       └── materials/
+│   └── 223015c/
+│       └── slides/
+│           ├── 2025-12-20-termin-1-geschichte-grundlagen-html.md
+│           └── assets/
+├── scripts/
+│   └── generate-index.sh
+├── themes/
+│   └── custom-theme.css
+├── build/           # Generated output
+├── flake.nix        # Nix flake with tools
+├── Makefile
+└── package.json
+```
+
+---
+
+## Slides erstellen
+
+### Frontmatter
+
+```yaml
+---
+marp: true
+theme: uncover
+paginate: true
+backgroundColor: #fff
+---
+```
+
+### Slide-Trennung
+
+```markdown
+# Slide 1
+
+Content
+
+---
+
+# Slide 2
+
+More content
+```
+
+### Bilder
+
+```markdown
+![Alt text](./assets/image.jpg)
+```
+
+### Themes
+
+Built-in: `default`, `gaia`, `uncover`
+Custom: in `themes/` Verzeichnis
+
+---
+
+## License
+
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)