malta-slides/AGENTS.md

AGENTS.md - Agent Guidelines for malta-slides-marp

This project builds a presentation deck for Marp based on Markdown files.

Agent Restrictions

• Agent NEVER runs commands on its own except changing files INSIDE THIS FOLDER, never any other then this
• Agent NEVER runs build commands or any automated processes without explicit user request, as the user is working in dev mode

Build Commands

• npm run build - Build slides from Markdown using Marp
• npm run dev - Start development server at http://localhost:8080
• npm run watch - Watch mode for live preview during development
• npm run export:pdf - Export slides to PDF format
• npm run export:html - Export slides to HTML format

Test Commands

• npm test - Run all tests
• npm run test:watch - Run tests in watch mode
• npm run test -- --testNamePattern="specific test name" - Run single test

Code Style Guidelines

File Structure

• Use slides/ directory for Markdown slide files
• Use assets/ directory for images and media files
• Always address images as ./assets/filename.png, not assets/ or ../assets/
• Use themes/ for custom Marp themes
• Use build/ directory for generated output files (ignored by git)

Naming Conventions

• Slide files: index.md, additional-slides.md (descriptive names)
• Images: snake_case.jpg or kebab-case.jpg
• Themes: custom-theme.css

Markdown Style

• Use ATX-style headers (# ## ###)
• Consistent code block language identifiers
• Frontmatter for slide metadata (title, theme, etc.)
• Never include a final --- as it creates an unwanted empty slide

Error Handling

• Validate Marp syntax before build
• Check for missing assets before export
• Log build errors with file paths and line numbers

Git Workflow

• Commit slide changes with descriptive messages (ALWAYS lowercase)
• Use feature branches for major slide revisions
• Tag releases with version numbers

Makefile Commands

• make build - Build slides from Markdown
• make dev - Start development server
• make watch - Watch for changes and rebuild
• make pdf - Export slides to PDF
• make html - Export slides to HTML
• make clean - Remove generated files
• make install - Install dependencies
• make deploy - Deploy slides to server