malta-slides/README.md

# Digital Independence Day

A presentation deck for the Digital Independence Day workshop, 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 for the **Digital Independence Day** event. It supports HTML, PDF, and PowerPoint export formats with live preview capabilities.

### Event Information

- **Event**: Digital Independence Day
- **Organized by**: Science in the City Malta
- **Date**: Wednesday, September 17, 2025 · 7-9pm CEST
- **Location**: APS Hub, Triq Mikiel Ang Borg San Ġiljan SPK 1000 St. Julian's
- **Description**: Workshop to explore GNU/Linux, an easy, affordable alternative to big tech. Hands-on session for beginners, no experience needed. Bring a laptop with a USB port.
- **Target Audience**: Teens and adults aged 16+
- **Focus**: Empowering digital independence through free and open source software

For more details, visit the [event page](https://www.eventbrite.com/e/digital-independence-day-tickets-1621757232539).

## 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:8080` 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)
│   └── index.md           # Main slide file
│   └── ...
├── 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: uncover
paginate: true
---

# Slide Title

Content here

---

# Next Slide

More content
```

### Frontmatter

Configure slide settings at the top:

```yaml
---
marp: true
theme: uncover
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 8080 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.