Michael Czechowski
9e12447528
- 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
197 lines
6.4 KiB
Markdown
197 lines
6.4 KiB
Markdown
# 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 |