This project uses Marp 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.

Prerequisites

Node.js v14 or higher
npm (comes with Node.js)
Chrome or Chromium browser (for PDF export)

Installation

Clone or download this repository
Install dependencies:
```
npm install
```

Usage

Development Server

Start the development server for live preview:

npm run dev

This starts a server at http://localhost:8080 showing your presentation.

Build Slides

Generate HTML files from Markdown:

npm run build

Output files are created in the build/ directory (ignored by git).

Export Formats

PDF Export

npm run export:pdf

Generates PDF files in the build/ directory (ignored by git).

HTML Export

npm run export:html

Generates standalone HTML files in the build/ directory (ignored by git).

Watch Mode

Automatically rebuild when files change:

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 (ignored by git)
├── 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 ---:

---
marp: true
theme: uncover
paginate: true
---

# Slide Title

Content here

---

# Next Slide

More content

Frontmatter

Configure slide settings at the top:

---
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:

![Alt text](assets/image.jpg)

Custom Themes

Create custom themes in themes/ directory:

/* @theme custom-theme */

@import-theme "gaia";

section {
  background-color: #f0f8ff;
  color: #2c3e50;
}

h1 {
  color: #3498db;
}

Apply custom theme in frontmatter:

---
marp: true
theme: custom-theme
---

Development Workflow

Edit slide files in slides/ directory
Use npm run dev for live preview
Make changes and see updates automatically
Export final version with npm run export:pdf

Makefile Commands

Alternative commands using Make:

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
make deploy     # Deploy slides to server

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

Follow the file structure conventions
Use numbered prefixes for slide files
Test builds before committing
Keep commit messages lowercase and descriptive

License

This project is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).

This project uses Marp which is MIT licensed.