add readme with usage and development instructions

2025-09-13 19:08:29 +02:00
parent e5f219507f
commit e6c45b0a06
1 changed files with 208 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,208 @@
+# Malta Slides - Marp Presentation Deck
+
+A presentation deck built with Marp for creating beautiful slide decks from Markdown files.
+
+## Overview
+
+This project uses [Marp](https://marp.app/) to convert Markdown files into presentation slides. It supports HTML, PDF, and PowerPoint export formats with live preview capabilities.
+
+## Prerequisites
+
+- Node.js v14 or higher
+- npm (comes with Node.js)
+- Chrome or Chromium browser (for PDF export)
+
+## Installation
+
+1. Clone or download this repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Usage
+
+### Development Server
+
+Start the development server for live preview:
+```bash
+npm run dev
+```
+This starts a server at `http://localhost:8000` showing your presentation.
+
+### Build Slides
+
+Generate HTML files from Markdown:
+```bash
+npm run build
+```
+Output files are created in the `build/` directory.
+
+### Export Formats
+
+#### PDF Export
+```bash
+npm run export:pdf
+```
+Generates PDF files in the `build/` directory.
+
+#### HTML Export
+```bash
+npm run export:html
+```
+Generates standalone HTML files in the `build/` directory.
+
+### Watch Mode
+
+Automatically rebuild when files change:
+```bash
+npm run watch
+```
+
+## File Structure
+
+```
+malta-slides-marp/
+├── slides/                 # Markdown slide files
+│   ├── index.md           # Main presentation file (served at root)
+│   ├── 01-intro.md        # Additional slide files
+│   └── ...
+├── assets/                # Images and media files
+├── themes/                # Custom CSS themes
+│   └── custom-theme.css   # Example custom theme
+├── build/                 # Generated output files
+├── node_modules/          # Dependencies
+├── package.json           # Project configuration
+├── Makefile               # Alternative build commands
+├── AGENTS.md              # Agent guidelines
+├── INIT_MARP.md           # Implementation guide
+└── README.md              # This file
+```
+
+## Creating Slides
+
+### Basic Slide Structure
+
+Slides are written in Markdown and separated by `---`:
+
+```markdown
+---
+marp: true
+theme: gaia
+paginate: true
+---
+
+# Slide Title
+
+Content here
+
+---
+
+# Next Slide
+
+More content
+```
+
+### Frontmatter
+
+Configure slide settings at the top:
+
+```yaml
+---
+marp: true
+theme: gaia
+paginate: true
+backgroundColor: #fff
+title: My Presentation
+---
+```
+
+### Themes
+
+Use built-in themes:
+- `default`
+- `gaia`
+- `uncover`
+
+Or create custom themes in `themes/` directory.
+
+### Images and Assets
+
+Place images in `assets/` directory and reference them:
+
+```markdown
+![Alt text](assets/image.jpg)
+```
+
+## Custom Themes
+
+Create custom themes in `themes/` directory:
+
+```css
+/* @theme custom-theme */
+
+@import-theme "gaia";
+
+section {
+  background-color: #f0f8ff;
+  color: #2c3e50;
+}
+
+h1 {
+  color: #3498db;
+}
+```
+
+Apply custom theme in frontmatter:
+```yaml
+---
+marp: true
+theme: custom-theme
+---
+```
+
+## Development Workflow
+
+1. Edit slide files in `slides/` directory
+2. Use `npm run dev` for live preview
+3. Make changes and see updates automatically
+4. Export final version with `npm run export:pdf`
+
+## Makefile Commands
+
+Alternative commands using Make:
+
+```bash
+make build      # Build slides
+make dev        # Start development server
+make pdf        # Export to PDF
+make html       # Export to HTML
+make watch      # Watch for changes
+make clean      # Remove generated files
+```
+
+## Tips
+
+- Use `---` to separate slides
+- Frontmatter controls global settings
+- Images should be in `assets/` directory
+- Custom themes extend built-in themes
+- PDF export requires Chrome/Chromium
+
+## Troubleshooting
+
+- **PDF export fails**: Ensure Chrome/Chromium is installed
+- **Server not starting**: Check if port 8000 is available
+- **Styles not applying**: Verify theme file paths
+- **Images not loading**: Check relative paths from slides directory
+
+## Contributing
+
+1. Follow the file structure conventions
+2. Use numbered prefixes for slide files
+3. Test builds before committing
+4. Keep commit messages lowercase and descriptive
+
+## License
+
+This project uses Marp which is MIT licensed.