rebuild dev and build system with single marp server

- simplify development: single marp server on port 3000 instead of 3 processes - rename klausur to klausurfolien for better naming - update extract script to use 00-intro.md as template when no 01-*.md exists - update makefile and package.json for new workflow - add comprehensive AGENTS.md guidelines
2026-02-01 18:17:51 +01:00
parent 7e4d4a8a4b
commit 9e12447528
11 changed files with 705 additions and 2337 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,197 @@
+# AGENTS.md - Agent Guidelines for HdM Slides
+
+This file contains comprehensive guidelines for agentic coding agents working on the HdM Slides project.
+
+## Project Overview
+
+This project builds presentation decks for Marp, supporting multiple courses:
+- **223015b** - Dateiformate, Schnittstellen, Speichermedien (6 Kapitel)
+- **223015c** - Internettechnologien (3 Kapitel)
+
+## Development Workflow
+
+### Build Commands
+```bash
+# Development
+make dev              # Start single dev server on port 3000
+npm run dev           # Alternative command for development server
+
+# Build
+make build            # Build all courses (HTML + PDF)
+make build-b          # Build 223015b only
+make build-c          # Build 223015c only
+make html             # HTML only builds
+make pdf              # PDF only builds
+
+# Klausur Folien
+make klausur          # Extract klausurfolien for all courses
+make klausur-b        # Extract klausurfolien for 223015b
+make klausur-c        # Extract klausurfolien for 223015c
+
+# Deployment
+make deploy            # Deploy all courses (requires explicit permission)
+make deploy-b         # Deploy 223015b only
+make deploy-c         # Deploy 223015c only
+
+# Utilities
+make qr URL=...       # Generate QR code
+make optimize-images COURSE=223015b  # Resize images
+make clean            # Remove generated files
+```
+
+### Testing
+No specific test framework is used. To validate changes:
+1. Start dev server: `make dev`
+2. Open http://localhost:3000/223015b/ or /223015c/
+3. Verify slides render correctly
+4. Run `make build` to ensure no build errors
+5. Check generated files in `build/` directory
+
+## Code Style Guidelines
+
+### File Structure
+- Slides in `slides/<course>/` following naming pattern `NN-topic.md`
+- Assets in `slides/<course>/assets/`
+- Always reference images as `./assets/filename.png`
+- Scripts in `scripts/`
+- Themes in `themes/`
+- Generated output in `build/` (gitignored)
+
+### Naming Conventions
+- Slide files: `NN-topic.md` (e.g., `01-grundlagen.md`, `02-bilder.md`)
+- Images: `snake_case.jpg` or `kebab-case.jpg`
+- Klausur files: `klausurfolien.md` (auto-generated)
+- Function names in scripts: `snake_case`
+- Variable names in scripts: `snake_case`
+
+### Markdown Style
+- Use ATX-style headers (`# ## ###`)
+- YAML frontmatter for slide metadata at top of each file
+- Never include a final `---` (creates empty slide)
+- Use `<!-- _class: klausur -->` for exam-relevant slides
+- Use relative paths for assets: `./assets/image.png`
+
+### Script Style
+- Use `#!/usr/bin/env bash` shebang
+- Use `set -e` for error handling
+- Use `2>/dev/null || true` for optional operations
+- Define variables in UPPER_CASE at script top
+- Use colors for terminal output: `\033[0;32m` etc.
+
+### Git Workflow
+- Commit messages: ALWAYS lowercase
+- NEVER add co-authoring lines or generated footers
+- Follow semantic naming: "add-...", "fix-...", "update-..."
+- Commit changes to scripts, Makefile, documentation separately from slide content
+
+## Agent Restrictions
+
+### Security
+- NEVER run commands outside `/home/mwc/Coding/hdm` folder
+- NEVER run build/deploy commands without explicit user request
+- NEVER run deploy commands (make deploy, scp, etc.) without explicit permission
+
+### File Protection
+Slide files in `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
+
+### Klausur Handling
+- Klausur files (`klausurfolien.md`) are auto-generated
+- NEVER edit klausurfolien.md files directly
+- To update klausurfolien: edit source slides with `<!-- _class: klausur -->` markers
+- Run `make klausur` to regenerate
+
+## Development Patterns
+
+### Adding New Slides
+1. Create new file following `NN-topic.md` pattern
+2. Copy frontmatter from existing slides in the same course
+3. Update Makefile `_KAPITEL` variable if needed
+4. Test with `make dev`
+
+### Modifying Existing Slides
+1. Edit the appropriate markdown file in `slides/<course>/`
+2. Maintain consistent styling with course theme
+3. Preserve image paths as `./assets/...`
+4. Test changes with dev server
+
+### Working with Assets
+1. Place images in `slides/<course>/assets/`
+2. Use descriptive names: `diagram-network.jpg`, `example-code.png`
+3. Optimize with `make optimize-images COURSE=223015b`
+4. Reference as `./assets/filename.ext`
+
+### Course-Specific Configuration
+Each course has specific settings in Makefile:
+- Course name and title
+- Kapitel list (slide files)
+- Deploy path
+- Theme colors (in generate-index.sh)
+
+## Common Tasks
+
+### Debugging Build Issues
+1. Check Makefile syntax: `make -n build`
+2. Verify Marp CLI installation: `npx @marp-team/marp-cli --version`
+3. Check file permissions: `ls -la slides/`
+4. Validate markdown syntax with dev server
+
+### Updating Course Structure
+1. Update `_KAPITEL` variables in Makefile
+2. Ensure slide files follow naming convention
+3. Update course-specific themes if needed
+4. Test both dev and build processes
+
+### Working with Themes
+- Custom theme in `themes/custom-theme.css`
+- Course themes defined in individual slide frontmatter
+- Use consistent color schemes per course
+- Test theme changes across all slides
+
+## Deployment Process
+
+Deployment to production server requires explicit permission:
+1. Build process: `make build` (HTML + PDF)
+2. Index generation: automatically handled
+3. Deploy to remote server via SCP
+4. Root index deployment
+
+**IMPORTANT**: Never run deployment commands without explicit user permission.
+
+## Tools and Dependencies
+
+### Core Dependencies
+- Marp CLI for slide rendering
+- Bash scripts for automation
+- Make for build orchestration
+- Git for version control
+
+### Optional Tools
+- qrencode for QR generation (via nix)
+- ImageMagick for image optimization
+- Python 3 for simple HTTP server (legacy)
+
+## Testing Strategy
+
+Since there's no formal test suite:
+1. Manual testing with dev server
+2. Build process validation
+3. Slide rendering checks
+4. Asset path verification
+5. Cross-browser compatibility checks (important)
+
+## Troubleshooting
+
+### Common Issues
+- **Port conflicts**: Use `make dev-kill` to clean up processes
+- **Build failures**: Check file permissions and Marp CLI installation
+- **Asset loading**: Verify relative paths and file existence
+- **Deploy issues**: Check SSH keys and remote permissions
+
+### Getting Help
+1. Check this AGENTS.md file first
+2. Review Makefile targets and scripts
+3. Test changes incrementally
+4. Maintain backup of working configurations