# Malware & Monsters Makefile Build System

*Last updated: 2025-08-11 - Added content measurement tools and configuration management*

## Quick Start

```bash
# Show all available commands
make help

# Build everything (HTML + PDF + Slides)
make all

# Build without cache (fresh build)
make all-nocache

# Build and serve locally  
make serve

# Quick HTML-only build
make quick

# Export aggregated plain-text handbooks for AI workflows
make text-handbooks

# Clean and rebuild everything
make clean all
```

## Watch Mode Requirements

The `make watch` target relies on [`entr`](https://eradman.com/entrproject/) to listen for file changes. Install it once per machine:

```bash
# macOS
brew install entr

# Debian / Ubuntu
sudo apt install entr

# Fedora
sudo dnf install entr

# openSUSE
sudo zypper install entr

# FreeBSD
pkg install entr
```

If `entr` isn't installed, the Makefile prints a guidance message and exits cleanly. You can always fall back to `quarto preview` for live reloads.

## Available Commands

### 🏗️ Main Build Targets

| Command | Description |
|---------|-------------|
| `make all` | Build everything (HTML + PDF + Slides) |
| `make all-nocache` | Build everything without cache (fresh build) |
| `make html` | Build all HTML versions only |
| `make pdf` | Build all PDF versions only |
| `make slides` | Build all RevealJS slides |
| `make players` | Build Players Handbook (HTML + PDF) |
| `make im` | Build IM Handbook (HTML + PDF) |

### 🎬 Slides & Presentations

| Command | Description |
|---------|-------------|
| `make slides` | Build all RevealJS slides (auto-updates manifest) |
| `make update-slides-manifest` | Update slides manifest with discovered decks |
| `make present` | Build slides and serve presentation server |
| `make slide-template` | Create a new slide template |

### ⚡ Quick Development

| Command | Description |
|---------|-------------|
| `make quick` | Quick HTML + slides build (no PDFs) |
| `make text-handbooks` | Generate `_output/text/players-handbook.txt` and `_output/text/im-handbook.txt` AI bundles |

### 🔧 LaTeX & PDF Support

| Command | Description |
|---------|-------------|
| `make check-latex` | Check LaTeX installation status |
| `make install-tinytex` | Install TinyTeX for PDF support |
| `make install-latex-packages` | Install common missing LaTeX packages |
| `make fix-lua-ul` | Fix specific lua-ul package issue |
| `make ensure-latex` | Ensure LaTeX is installed and working |

### 🌐 Local Development

| Command | Description |
|---------|-------------|
| `make serve` | Build HTML and serve on localhost:8000 |
| `make watch` | Watch for changes and rebuild automatically (requires `entr`) |
| `make validate` | Validate build output and show statistics |
| `make test-404` | Test deployment for HTTP 404 errors |
| `make test-deploy` | Run full deployment test suite |
| `make check-deps` | Check if required dependencies are installed |

### 🧪 Testing & Validation

| Command | Description |
|---------|-------------|
| `make test-404` | Test deployment for HTTP 404 errors |
| `make test-deploy` | Run comprehensive deployment test suite |
| `./scripts/test-404-errors.sh` | Direct 404 testing script |

**Testing Requirements:**
- Requires deployed site (testing or production)
- Internet connection for remote URL testing
- Tests run comprehensive link checking and critical page validation

### 🧹 Cleanup & Maintenance

| Command | Description |
|---------|-------------|
| `make clean` | Remove all generated files |
| `make clean-cache` | Remove Quarto cache files |
| `make check-config` | Check handbook configurations for corruption |

### 🤖 Text & AI Workflows

Use `make text-handbooks` to create two aggregated plain-text exports—one for the Players Handbook and one for the IM Handbook. Each run depends on the normal HTML build, then concatenates every chapter, resource, scenario card, walkthrough, and practical tool page into `_output/text/players-handbook.txt` and `_output/text/im-handbook.txt`. The files strip visual styling, keep structural headings, and carry per-page separators so AI pipelines receive the maximum relevant context with minimal preprocessing.

### 🚀 Advanced Options

| Command | Description |
|---------|-------------|
| `make NO_CACHE=1 all` | Build everything without cache |
| `make help` | Show detailed help with examples |

## New Features

### 🎬 RevealJS Slide Support

The build system now includes comprehensive support for RevealJS presentations:

**Creating Slides:**
```bash
# Create your first slide template
make slide-template

# Edit slides/template.qmd and build
make slides

# Serve slides with presentation mode
make present
```

**Slide Features:**
- 🎨 Custom Malware & Monsters theme
- 📱 Mobile-responsive design
- 🧭 Cross-navigation system (press 'H' during presentation)
- 🔄 Dynamic slide deck discovery and manifest management
- 🎯 Logo and branding integration
- 📊 Support for LUA filters (malmon cards, type charts, ATT&CK)
- 🖊️ Chalkboard support for annotations
- ⚡ Smooth transitions and animations
- 🔗 Seamless integration with handbooks and main site

### 🔧 LaTeX Installation Options

The build system supports multiple LaTeX installations and provides appropriate guidance for each:

**Option 1: Debian/Ubuntu System Packages (Recommended for Linux)**
```bash
# Install via system package manager
sudo apt update
sudo apt install texlive-base texlive-luatex texlive-fonts-recommended texlive-latex-extra

# (Note: No automated Makefile target for this)
```

**Option 2: TinyTeX (Cross-platform)**
```bash
# Install TinyTeX via Quarto
make install-tinytex

# Install common packages
make install-latex-packages
```

**Choosing Between Options:**

**Debian/Ubuntu Packages:**
- ✅ System-managed updates via `apt`
- ✅ Proper integration with system dependencies  
- ✅ No PATH configuration issues
- ✅ More predictable behavior on Linux systems
- ❌ Larger installation size
- ❌ Less flexible package management

**TinyTeX:**
- ✅ Smaller installation size
- ✅ Easy package management via `tlmgr`
- ✅ Cross-platform consistency
- ✅ Designed specifically for Quarto/R Markdown
- ❌ May require PATH configuration
- ❌ Can conflict with system TeX installations

**Clear Error Guidance:**
When PDF builds fail, the makefile detects your LaTeX installation and provides specific guidance:

```bash
📖 Building Players Handbook (PDF)...
❌ PDF build failed
📋 Common PDF build issues:
💡 System TeX Live detected. Try: sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra
💡 Or install TinyTeX: make install-tinytex
💡 Check LaTeX status: make check-latex
```

**Simple Fix Commands:**
```bash
# For Debian/Ubuntu system TeX Live
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# For TinyTeX installations  
make fix-lua-ul

# Check what you currently have
make check-latex
```

### 🚀 Cache Management

**Fresh Builds:**
```bash
# Build without using any cached content
make NO_CACHE=1 all

# Or use the convenience target
make all-nocache

# Clean cache files specifically
make clean-cache

# Clean everything including cache
make clean
```

**When to Use Fresh Builds:**
- After updating shared styles or themes
- When troubleshooting build issues
- Before final deployment
- After major Quarto updates

## Intelligent Dependency Tracking

The Makefile automatically tracks dependencies:

- **Main site** rebuilds when `index.qmd`, `community.qmd`, or `_quarto.yml` changes
- **Players Handbook** rebuilds when any `.qmd` or `.yml` file in `players-handbook/` changes
- **IM Handbook** rebuilds when any `.qmd` or `.yml` file in `im-handbook/` changes
- **Slides** rebuild when slide source files or shared resources change
- **All content** rebuilds when shared resources (CSS, SCSS, Lua filters) change

This means:
- ✅ Only changed content gets rebuilt
- ✅ Fast incremental builds during development
- ✅ Guaranteed consistency when shared files change
- ✅ Automatic LaTeX setup when PDF builds are needed

## Development Workflows

### First Time Setup
```bash
# Check all dependencies
make check-deps

# Ensure LaTeX is available for PDFs
make check-latex

# Full build and test
make all
make validate
```

### Daily Development
```bash
# Quick build for development
make quick

# Watch for automatic rebuilding
make watch          # Requires entr
# (in another terminal)
make serve
```

### Content Writing
```bash
# Work on players handbook
make players && make serve

# Work on IM handbook  
make im && make serve

# Work on slides
make slides && make present

# Work on main site
make quick && make serve
```

### Presentation Development
```bash
# Create and edit slides
mkdir slides/my-presentation
# Edit slides/my-presentation/slides.qmd

# Build with automatic manifest update
make slides

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

# Update manifest only
make update-slides-manifest
```

### Troubleshooting PDF Issues

**Simple PDF troubleshooting workflow:**

The makefile automatically detects your LaTeX installation type and provides appropriate guidance:

```bash
# 1. Try building PDF
make pdf

# 2. If it fails, you'll see installation-specific guidance:

# For Debian/Ubuntu system TeX Live:
📖 Building Players Handbook (PDF)...
❌ PDF build failed
💡 System TeX Live detected. Try: sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra
💡 Or install TinyTeX: make install-tinytex

# For TinyTeX installations:
💡 Missing LaTeX packages? Try: make fix-lua-ul
💡 Need full package install? Try: make install-latex-packages

# 3. Follow the specific guidance for your system:

# Debian/Ubuntu users (recommended):
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# TinyTeX users:
make fix-lua-ul

# Check current setup:
make check-latex
```

**Installation-Specific Solutions:**

**Debian/Ubuntu System TeX Live:**
```bash
# Install missing packages via apt
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Manual installation
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Check what's installed
dpkg -l | grep texlive
```

**TinyTeX Installation:**
```bash
# Install missing packages via tlmgr
make fix-lua-ul

# Comprehensive package installation
make install-latex-packages

# Manual package management
~/.TinyTeX/bin/*/tlmgr install lua-ul
```

**PATH Issues with TinyTeX:**
If you have both TinyTeX and system TeX Live installed, you may need to ensure TinyTeX is in your PATH:
```bash
# Add to ~/.bashrc
export PATH="$HOME/.TinyTeX/bin/x86_64-linux:$PATH"

# Reload shell
source ~/.bashrc

# Verify TinyTeX is found first
which tlmgr
```

**Migration Between Systems:**
```bash
# Remove TinyTeX and use system packages
quarto uninstall tinytex
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Remove system packages and use TinyTeX
sudo apt remove texlive-*
make install-tinytex
```

**No Complex Automation:**
The build system keeps error handling simple and reliable:
- ✅ Detects your specific LaTeX installation type
- ✅ Provides installation-specific fix commands
- ✅ HTML fallback so builds don't fail completely  
- ✅ Clear guidance for both Debian packages and TinyTeX
- ❌ No automatic package installation during builds
- ❌ No complex PATH manipulation

### Before Committing
```bash
# Full clean build with validation
make clean all validate
```

## Build Output Structure

```
_output/
├── index.html                    # Main site
├── community.html               # Community page
├── players-handbook/
│   ├── index.html              # Players book main page
│   ├── chapters/               # All chapters
│   └── resources/              # Quick references
├── im-handbook/
│   ├── index.html              # IM book main page  
│   ├── chapters/               # All chapters
│   └── resources/              # IM resources
├── shared/
│   └── glossary.html           # Shared glossary
├── slides/                      # RevealJS presentations
│   ├── template.html           # Generated slide decks
│   └── other-slides.html       # Additional presentations
├── players-handbook.pdf         # PDF download
├── im-handbook.pdf             # PDF download
└── site_libs/                  # Quarto assets
```

## Advanced Features

### Slide Development

**Template Structure:**
```yaml
---
title: "Your Presentation"
format:
  revealjs:
    theme:
      - ../_scss/revealjs/_unified-reveal-bridge.scss
    logo: ../shared/logo.png
    footer: "Malware & Monsters"
    slide-number: true
    chalkboard: true
filters:
  - ../shared/malmon-card-filter.lua
---
```

**Presentation Server:**
```bash
# Start presentation server with all slides
make present

# Slides available at http://localhost:8000/slides/
# Use presenter mode with 'S' key
# Draw on slides with 'B' key (chalkboard)
```

### LaTeX Error Recovery

The build system provides clear, reliable error guidance without complex automation:

**Error Handling Philosophy:**
- **Simple and reliable** - Clear error messages with specific fix commands
- **Non-blocking** - HTML versions built automatically when PDF fails
- **Progressive guidance** - From simple fixes to comprehensive solutions
- **No automation complexity** - Users run fix commands when ready

**When PDF Builds Fail:**
```bash
📖 Building Players Handbook (PDF)...
❌ PDF build failed
📋 Common PDF build issues:
💡 Missing LaTeX packages? Try: make fix-lua-ul
💡 Need full package install? Try: make install-latex-packages  
💡 No LaTeX installed? Try: make install-tinytex
💡 Check LaTeX status: make check-latex

Building HTML version instead...
✅ Players HTML built
```

**Fix Commands Explained:**

1. **`make fix-lua-ul`** - Installs the lua-ul package (most common missing package)
2. **`make install-latex-packages`** - Installs comprehensive collection of common packages  
3. **`make install-tinytex`** - Installs TinyTeX if no LaTeX distribution is present
4. **`make check-latex`** - Shows current LaTeX installation status

**Common Packages Installed by Fix Commands:**
- `lua-ul` - Advanced underlining for LuaLaTeX (most common missing package)
- `luacolor` - Color support via LuaTeX attributes  
- `fontspec` - Font selection for XeLaTeX and LuaLaTeX
- `unicode-math` - Unicode mathematics support
- `collection-fontsrecommended` - Recommended font collection
- `collection-latexextra` - Extra LaTeX packages for advanced features

**Reliable Workflow:**
1. Run `make pdf` or `make all`
2. If PDF fails, see clear guidance message
3. Run suggested fix command (usually `make fix-lua-ul`)
4. Run `make pdf` again to retry
5. PDF should now build successfully

### Cache Optimization

**Cache Behavior:**
- HTML builds use cache by default for faster rebuilds
- PDF builds may bypass cache for certain packages
- Slides cache templates and themes
- Shared resources invalidate all dependent caches

**Cache Control:**
```bash
# Force fresh build of everything
make NO_CACHE=1 all

# Clean cache but keep output
make clean-cache

# See what would be rebuilt
make -n all
```

## Environment Customization

### Build Flags
```bash
# Build without cache
NO_CACHE=1 make all

# Custom output directory
OUTPUT_DIR=dist make all

# Parallel builds (experimental)
MAKEFLAGS=-j4 make html
```

### LaTeX Configuration
```bash
# Check LaTeX status
make check-latex

# Force TinyTeX reinstall
rm -rf ~/.TinyTeX
make install-tinytex

# Manual package installation
tlmgr install specific-package-name
```

## Troubleshooting

### Common Issues

### Common Issues

### Common Issues

**LaTeX/PDF Problems:**

The makefile detects your LaTeX installation type and provides specific guidance:

```bash
# The makefile will show you installation-specific commands:

# For Debian/Ubuntu system TeX Live:
💡 System TeX Live detected. Try: sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# For TinyTeX installations:
💡 Missing LaTeX packages? Try: make fix-lua-ul

# For no LaTeX installation:
💡 No LaTeX installed? Try: make install-tinytex
```

**Specific Error Solutions:**

**Debian/Ubuntu System TeX Live** (recommended for Linux):
```bash
# Most common solution
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Manual approach
sudo apt update
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra
```

**TinyTeX Installation:**
```bash
# Fix missing lua-ul package
make fix-lua-ul

# Install comprehensive packages
make install-latex-packages

# Manual approach
~/.TinyTeX/bin/*/tlmgr install lua-ul
```

**No LaTeX installed:**
```bash
# Option 1: System packages (Linux)
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Option 2: TinyTeX (cross-platform)
make install-tinytex
```

**Mixed installations** (TinyTeX + system packages):
```bash
# Check what's being used
make check-latex
which tlmgr

# Use system packages (remove TinyTeX)
quarto uninstall tinytex
sudo apt install texlive-luatex texlive-fonts-recommended texlive-latex-extra

# Use TinyTeX (remove system packages)
sudo apt remove texlive-*
make install-tinytex
```

**Check current status:**
```bash
make check-latex
```

**Cache Issues:**
```bash
# Clear cache and rebuild
make clean-cache all

# Force fresh build
make NO_CACHE=1 all
```

**Slide Problems:**
```bash
# Clean slide cache
make clean

# Rebuild slides only
make slides

# Check slide template
make slide-template
```

**Build Dependencies:**
```bash
# Check all required tools
make check-deps

# Install missing tools as needed
```

### Debug Information

```bash
# Show detailed build status and LaTeX capabilities
make validate

# Check LaTeX installation and package availability
make check-latex

# Show help with all available commands
make help

# Test specific PDF build with verbose output
make NO_CACHE=1 pdf

# Check which packages are installed
tlmgr list --only-installed

# Search for specific packages
tlmgr search --global --file "/lua-ul.sty"
```

### Content Measurement and Analysis

The build system includes tools for measuring content consolidation progress and analyzing duplication:

**Content Metrics Collection:**
```bash
# Generate comprehensive content metrics report
./scripts/measure-content-metrics.sh

# Baseline metrics (automatically saved on first run)
# Subsequent runs show progress since baseline
```

**Key Performance Indicators Tracked:**
- **Line/Word Counts**: Total content across both handbooks
- **Shared Content Adoption**: Percentage of content in shared directories
- **Duplication Indicators**: Keyword analysis for duplicate concepts
- **Consolidation Progress**: Reduction metrics compared to baseline

**Sample Output:**
```
=== Content Consolidation Metrics Report ===
Players Handbook Lines: 11,479
IM Handbook Lines: 24,405
Shared Content Lines: 359
Total Handbook Lines: 35,884
Shared Content Adoption Rate: 8.00%

## Progress Since Baseline
Line Reduction: 425 (1.18%)
Consolidation Ratio: 3.2:1 (lines eliminated per shared line added)
```

**Integration with Content Consolidation:**
- Run before each consolidation phase to establish metrics
- Track progress toward 15-25% content reduction targets
- Monitor shared content adoption rate (target: 25-30%)
- Measure consolidation efficiency ratios

## Configuration Management

### Handbook Configuration Integrity

The build system includes automatic configuration corruption detection:

**Configuration Checking:**
```bash
# Check all handbook configurations
make check-config

# Included automatically in main build targets:
# make all, make quick, make html, make pdf
```

**Common Configuration Issues Detected:**
- **Wrong Project Types**: Handbooks accidentally set to `type: book` instead of `type: website`
- **Missing Navigation Elements**: Incomplete navbar inheritance
- **Corrupted YAML**: Malformed configuration files

**Automatic Error Recovery:**
```bash
# If corruption detected, build system provides fix commands:
git diff players-handbook/_quarto.yml im-handbook/_quarto.yml
git checkout -- players-handbook/_quarto.yml im-handbook/_quarto.yml
chmod 444 players-handbook/_quarto.yml im-handbook/_quarto.yml
```

**Configuration Best Practices:**
- Both handbooks use `type: website` for consistent theming
- Navigation inheritance patterns for PDF download consistency
- Automatic integrity checking prevents build failures
- Read-only permissions protect against accidental corruption

## Integration Examples

### VS Code Tasks
Add to `.vscode/tasks.json`:
```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build All",
            "type": "shell",
            "command": "make all",
            "group": "build"
        },
        {
            "label": "Build Fresh",
            "type": "shell",
            "command": "make all-nocache",
            "group": "build"
        },
        {
            "label": "Present Slides",
            "type": "shell",
            "command": "make present",
            "group": "build"
        },
        {
            "label": "Serve",
            "type": "shell", 
            "command": "make serve",
            "group": "build"
        }
    ]
}
```

### GitHub Actions with LaTeX
```yaml
name: Build Documentation
on: [push, pull_request]
jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v3
      - uses: quarto-dev/quarto-actions/setup@v2
      - name: Check dependencies
        run: make check-deps
      - name: Install LaTeX
        run: make install-tinytex
      - name: Build all content
        run: make all
      - name: Validate output
        run: make validate
      - name: Upload slides
        uses: actions/upload-artifact@v3
        with:
          name: slides
          path: _output/slides/
```

### Docker Development
```dockerfile
FROM quarto/quarto:latest

# Install make and build dependencies
RUN apt-get update && apt-get install -y make python3

# Install TinyTeX for PDF support
RUN quarto install tinytex

WORKDIR /workspace
COPY . .

# Build everything
RUN make check-deps && make all

EXPOSE 8000
CMD ["make", "serve"]
```

## Tips for Maximum Efficiency

1. **Use targeted builds** during development:
   - `make quick` for HTML + slides only
   - `make players` for specific handbook
   - `make slides` for presentations only

2. **Leverage caching** for faster builds:
   - Default builds use cache for speed
   - Use `make all-nocache` only when needed

3. **Automate LaTeX setup**:
   - Run `make check-latex` on new systems
   - Use `make install-tinytex` for automatic setup

4. **Optimize presentation workflow**:
   - Use `make present` for slide development
   - Edit slides in real-time with browser refresh

5. **Clean selectively**:
   - `make clean-cache` for cache issues
   - `make clean` for complete cleanup

6. **Monitor build health and fix issues easily**:
   - Use `make validate` to check output
   - Use `make check-deps` to verify setup
   - When PDF builds fail, follow the clear guidance messages
   - Use `make fix-lua-ul` for the most common missing package issue
   - Use `make install-latex-packages` for comprehensive package installation

The enhanced Makefile system provides a complete, professional build process with clear error guidance that tells you exactly which commands to run when issues occur. No complex automation means more reliable builds and easier troubleshooting.