From 3c78c898dd58734331714844db6c363917e8eba6 Mon Sep 17 00:00:00 2001 From: Michael Czechowski Date: Tue, 30 Dec 2025 11:30:45 +0100 Subject: [PATCH] add documentation - README.md: project overview, commands, structure - CLAUDE.md: agent guidelines for slide editing --- CLAUDE.md | 74 ++++++++++++++++++++++ README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a61e2bc --- /dev/null +++ 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 -- # Optimize images +``` + +## Code Style Guidelines + +### File Structure +- Slides in `courses//slides/` +- Assets in `courses//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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..95902cd --- /dev/null +++ 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/)