# Slides Integration Guide

## Overview

The Malware & Monsters project includes a comprehensive RevealJS slides system with unified theming, dynamic cross-navigation, and presentation-friendly features designed specifically for cybersecurity education and training.

## Quick Start

### 1. Create Your First Slide Deck

Create a new directory under `slides/` and add a `slides.qmd` file:

```bash
mkdir slides/my-presentation
```

```yaml
---
title: "Your Presentation Title" 
subtitle: "Subtitle"
author: "Your Name"
date: today
format:
  revealjs:
    theme:
      - ../../_scss/revealjs/_unified-reveal-bridge.scss
      - ../../_scss/_slides-nav.scss
    chalkboard: false
filters:
  - ../../shared/filters/malmon-card-filter.lua
  - ../../shared/filters/type-chart-filter.lua
  - ../../shared/filters/attck-mapping-filter.lua
---

# Your First Slide {background-color="#2c3e50"}

Content goes here...
```

### 2. Build and Present

```bash
# Build all slides (automatically updates manifest)
make slides

# Present locally
make serve
# Navigate to http://localhost:8000/slides/my-presentation/slides.html
```

## File Structure

```
slides/
├── _quarto.yml                    # Slides project configuration
├── manifest.json                  # Auto-generated slide deck registry
└── my-presentation/
    └── slides.qmd                 # Your slide deck

_scss/
├── revealjs/
│   └── _unified-reveal-bridge.scss # RevealJS theme integration
└── _slides-nav.scss               # Navigation overlay styles

shared/js/
└── slides-cross-nav.js            # Cross-navigation functionality

scripts/
└── update-slides-manifest.js      # Automatic manifest generator
```

## Cross-Navigation System

### 🎯 Presentation-Friendly Navigation

The slides include a **completely non-intrusive** cross-navigation system:

**Key Features:**
- **Hidden by Default**: No visible UI during presentations  
- **Keyboard-Triggered**: Press 'H' to show navigation overlay
- **Presenter-Controlled**: Easy to access resources without disrupting flow
- **Reveal.js Integration**: Pauses presentation navigation while active

**Usage During Presentations:**
- **'H' Key**: Toggle navigation overlay
- **ESC Key**: Close navigation overlay
- **'T' Key**: Toggle light/dark theme
- **All Other Keys**: Normal RevealJS presentation controls

### 🎨 Dynamic Theme Switching

The slides include built-in light/dark mode support for different presentation environments:

**Key Features:**
- **Automatic Detection**: System preference detected on first load
- **Keyboard Shortcut**: Press 'T' to toggle between light and dark modes
- **Visual Toggle Button**: Small button (top-right) for mouse-based switching
- **Persistent Preference**: Choice saved in localStorage across sessions
- **Smooth Transitions**: Animated theme changes don't disrupt presentation flow

**When to Use:**
- **Light Mode**: Well-lit rooms, daylight presentations, projected on white walls
- **Dark Mode**: Dimly lit rooms, evening presentations, large screens in dark venues

**Theme Configuration:**

The theme is automatically included via `_slides-nav.scss`:

```yaml
format:
  revealjs:
    theme:
      - ../../_scss/revealjs/_unified-reveal-bridge.scss
      - ../../_scss/_slides-nav.scss  # Includes theme toggle
```

No additional configuration needed - theme toggle works out of the box.

### 🔗 Navigation Features

When you press 'H' during a presentation, you get:

1. **Other Slide Decks**: Navigate to different presentations
2. **Related Handbooks**: Jump to relevant sections for deeper information
3. **Workshop Resources**: Context-aware suggestions based on slide content
4. **Main Site**: Access community resources and project overview

### 🔄 Dynamic Slide Discovery

The system automatically discovers and manages slide decks:

```bash
# Automatic manifest update
make slides  # Updates manifest.json, then builds slides

# Manual manifest update  
make update-slides-manifest
```

**Manifest Structure** (`slides/manifest.json`):
```json
{
  "slides": [
    {
      "id": "my-presentation",
      "title": "My Presentation",
      "description": "Description from slide frontmatter",
      "path": "my-presentation/slides.html",
      "authors": ["Your Name"],
      "tags": ["workshop", "training"],
      "active": true
    }
  ],
  "meta": {
    "last_updated": "2025-07-28",
    "auto_generated": true
  }
}
```

## Using LUA Filters in Slides

### Available Filters

The slides system includes all the same LUA filters as the handbooks:

```yaml
filters:
  - ../../shared/filters/malmon-card-filter.lua    # Malmon card rendering
  - ../../shared/filters/type-chart-filter.lua     # Type effectiveness charts
  - ../../shared/filters/attck-mapping-filter.lua  # MITRE ATT&CK integration
```

### 1. Malmon Cards in Slides

Use the same syntax as in handbooks:

```markdown
# Malware Showcase

:::{.malmon-card}
**Name:** GaboonGrabber
**Type:** Trojan
**Threat Level:** ⭐⭐
**Real Malware:** Gaboon Viper APT

**Stats:**
- Stealth: 8/10
- Impact: 6/10
- Persistence: 7/10

**MITRE ATT&CK:** T1055 (Process Injection)
:::
```

The filter automatically renders this as a styled card with:
- Proper malware theming
- Statistical displays
- MITRE ATT&CK technique integration
- Consistent visual design

### 2. Type Effectiveness Charts

Display type matchups during gameplay explanations:

```markdown
# Combat Mechanics

:::{.type-chart}
attacking: Detector
defending: Rootkit
:::
```

This renders an interactive type effectiveness display showing:
- Attack/defense relationship
- Effectiveness multipliers
- Visual indicators (super effective, not very effective, etc.)

### 3. MITRE ATT&CK Integration

Reference real attack techniques in slides:

```markdown
# Real-World Connection

The Stuxnet malmon demonstrates several techniques:

- [[T1055]] Process Injection for persistence
- [[T1083]] File and Directory Discovery
- [[T1027]] Obfuscated Files or Information
```

The filter automatically:
- Links to MITRE ATT&CK framework
- Shows technique descriptions on hover
- Provides context for educational value

### 4. Filter Configuration

**In `slides/_quarto.yml`:**
```yaml
filters:
  - ../shared/filters/malmon-card-filter.lua
  - ../shared/filters/type-chart-filter.lua  
  - ../shared/filters/attck-mapping-filter.lua
```

**Individual Slide Deck Override:**
```yaml
---
title: "My Presentation"
format:
  revealjs:
    # ... theme config
filters:
  - ../../shared/filters/malmon-card-filter.lua  # Only include card filter
---
```

### 5. Presentation-Specific Styling

Filters adapt automatically for slide presentation:

- **Larger Text**: Readable from presentation distance
- **High Contrast**: Works well on projected screens
- **Simplified Layout**: Removes complex details for clarity
- **Animation Support**: Cards can appear with RevealJS fragments

```markdown
# Progressive Malmon Reveal

::: {.fragment}
:::{.malmon-card}
**Name:** Stuxnet
**Type:** Worm
:::
:::

::: {.fragment}
- Targets industrial control systems
- Real-world impact on Iranian nuclear facilities
:::

::: {.fragment}
**Learning Objective:** Understanding targeted attacks
:::
```

## Advanced Slide Features

### Themed Background Colors

Use brand colors for section transitions:

```markdown
# Introduction {background-color="#2c3e50"}
# Core Concepts {background-color="#3498db"}  
# Hands-on Demo {background-color="#e74c3c"}
# Implementation {background-color="#27ae60"}
# Conclusion {background-color="#8e44ad"}
```

### Role-Based Content

Highlight different incident response roles:

```markdown
::: {.role-highlight .detective}
🔍 **Detective Role**
Specializes in finding clues and analyzing evidence
:::

::: {.role-highlight .protector}  
🛡️ **Protector Role**
Focuses on stopping threats and securing systems
:::
```

### Interactive Elements

```markdown
# Workshop Flow

::: {.session-flow}
::: {.phase}
::: {.phase-number}1:::
::: {.phase-title}Discovery:::
::: {.phase-duration}25 minutes:::
:::

::: {.phase}
::: {.phase-number}2:::
::: {.phase-title}Investigation:::
::: {.phase-duration}25 minutes:::
:::
:::
```

### Speaker Notes

Add presenter-only information:

```markdown
# Key Learning Points

- Collaborative incident response
- Real-world malware connections
- Progressive skill development

::: {.notes}
- Emphasize the collaborative aspect - this isn't solo work
- Mention that malmons are based on real malware families
- Allow time for questions about the progression system
- Remember to demo the actual card interaction
:::
```

## Presentation Best Practices

### Structure for Education

1. **Clear Objectives**: What will participants learn?
2. **Real-World Context**: How does this apply to their work?
3. **Interactive Elements**: Use malmon cards and charts
4. **Progressive Disclosure**: Build complexity gradually
5. **Practical Application**: How to implement what they've learned

### Engagement Techniques

```markdown
# Interactive Demo

::: {.fragment}
Let's look at a real incident scenario...
:::

::: {.fragment}
:::{.malmon-card}
**Name:** WannaCry  
**Type:** Ransomware
**Real Impact:** Global healthcare disruption
:::
:::

::: {.fragment}
**Discussion:** How would your team respond?
:::
```

### Cross-Reference Integration

Reference handbook content during presentations:

```markdown
# Session Preparation

For detailed preparation steps, participants should review:
- Players Handbook Chapter 2 (press 'H' → Players Handbook)
- IM Handbook Chapter 3 (press 'H' → IM Handbook)

*Navigation tip: Press 'H' during this presentation to access resources*
```

## Build System Integration

### Makefile Commands

```bash
# Build all slides with manifest update
make slides

# Update slide registry only
make update-slides-manifest

# Build everything including slides  
make all

# Development server
make serve
```

### Automatic Discovery

New slide decks are automatically discovered and added to navigation:

1. Create new directory under `slides/`
2. Add `slides.qmd` file with proper frontmatter
3. Run `make slides`
4. New deck appears in all cross-navigation menus

### Deployment

Slides deploy with the rest of the documentation:

```bash
# Build for production
make all

# Generated slides in:
_output/slides/my-presentation/slides.html
```

## Troubleshooting

### Common Issues

**Navigation not working:**
- Ensure JavaScript is enabled
- Check browser console for errors
- Verify `slides-cross-nav.js` is loading

**Filters not processing:**
- Check LUA filter paths in frontmatter
- Verify filter files exist in `shared/filters/`
- Look for syntax errors in card/chart markup

**Manifest not updating:**
- Run `make update-slides-manifest` manually
- Check that Node.js is available
- Verify slide frontmatter is valid YAML

**Theme not applying:**
- Ensure SCSS paths are correct (`../../_scss/...`)
- Check that `_unified-reveal-bridge.scss` exists
- Verify Quarto can compile SCSS

**Theme toggle not working:**
- Verify `_slides-nav.scss` is included in theme list
- Check that `slides-theme-toggle.js` exists in `shared/js/`
- Ensure JavaScript file has proper permissions (644)
- Hard refresh browser: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
- Check browser console (F12) for JavaScript errors

### Performance Tips

- **Optimize Images**: Use appropriate sizes for web delivery
- **Minimize Fragments**: Too many can slow transitions  
- **Test Cross-Platform**: Verify on presentation hardware
- **Cache Considerations**: Browser may cache old versions

## Integration with Documentation

The slides system is fully integrated with the broader documentation ecosystem:

- **Shared Theming**: Consistent visual identity across all formats
- **Common Filters**: Same malmon cards work in slides and handbooks  
- **Cross-Navigation**: Seamless movement between content types
- **Unified Build**: Single command builds everything together

This creates a cohesive learning environment where presentations, handbooks, and interactive content work together to support cybersecurity education and training.