# Enabling Mermaid Diagrams in Marp Slides

Mermaid diagrams (```mermaid code blocks) do not render natively in Marp. This document describes how to enable Mermaid support in the MakerFLOSS slide build pipeline.

## Overview

Marp converts Markdown to HTML/PDF, but Mermaid requires JavaScript execution to render diagrams. The solution is to:

1. Configure Marp to transform mermaid code blocks into `<div class="mermaid">` elements
2. Inject the Mermaid.js library into the generated HTML
3. Initialize Mermaid on page load

## Setup Instructions

### Step 1: Add Dependencies

Create or update `package.json` in the repository root:

```json
{
  "name": "makerfloss-slides",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "./build-slides.sh"
  },
  "devDependencies": {
    "@marp-team/marp-cli": "^4.1.0",
    "@marp-team/marp-core": "^4.1.0"
  }
}
```

Install dependencies:

```bash
npm install
```

### Step 2: Create Marp Configuration

Create `marp.config.mjs` in the repository root:

```javascript
import { Marp } from '@marp-team/marp-core'

export default {
  html: true,
  engine: (constructorOptions) => {
    const marp = new Marp(constructorOptions)

    // Transform mermaid code blocks to divs that mermaid.js can render
    const { code } = marp.markdown.renderer.rules
    marp.markdown.renderer.rules.code = (tokens, idx, options, env, self) => {
      const token = tokens[idx]
      if (token.info.trim() === 'mermaid') {
        return `<div class="mermaid">${token.content}</div>`
      }
      return code(tokens, idx, options, env, self)
    }

    return marp
  }
}
```

### Step 3: Update build-slides.sh

Modify `build-slides.sh` to use the config file when available:

```bash
CONFIG="$REPO_ROOT/marp.config.mjs"

if command -v npx &>/dev/null && [ -f "$CONFIG" ]; then
  npx @marp-team/marp-cli --config "$CONFIG" --html --output "$OUTPUT_DIR/" "${SLIDES[@]}"
elif command -v marp &>/dev/null; then
  marp --html --output "$OUTPUT_DIR/" "${SLIDES[@]}"
else
  # ... existing Docker fallback ...
fi
```

### Step 4: Add Mermaid Script to Slides

In each Marp presentation that uses Mermaid diagrams, add the following after the frontmatter:

```markdown
---
marp: true
theme: gaia
class: invert
paginate: true
---

<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, theme: 'dark' });
</script>

# Your Slide Title
...
```

**Note:** Use `theme: 'dark'` for dark Marp themes (like `gaia` with `class: invert`), or `theme: 'default'` for light themes.

## Usage

After setup, build slides as usual:

```bash
# With npm
npm run build

# Or directly
./build-slides.sh
```

The generated HTML files in `slides/` will render Mermaid diagrams when viewed in a browser.

## Troubleshooting

### Diagrams not rendering

- Ensure the `<script>` tag is present in the slide markdown
- Check browser console for JavaScript errors
- Verify the Mermaid syntax is correct (test at https://mermaid.live)

### Diagrams render as code blocks

- Verify `marp.config.mjs` exists and is valid
- Ensure `--html` flag is passed to marp-cli
- Check that `npx` is available and `package.json` dependencies are installed

### PDF export

Mermaid diagrams may not render in PDF exports since they require JavaScript. Options:

1. Use `--html` output and print to PDF from browser
2. Pre-render diagrams as SVG images using mermaid-cli:
   ```bash
   npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg
   ```
   Then embed the SVG in your slides.

## Alternative: Docker with Mermaid

If using the Docker fallback, you'll need a custom Docker image or mount the config file. The standard `marpteam/marp-cli` image does not include mermaid support out of the box.

## References

- [Marp CLI Documentation](https://github.com/marp-team/marp-cli)
- [Mermaid.js Documentation](https://mermaid.js.org/)
- [Marp Custom Engine](https://github.com/marp-team/marp-cli#custom-engine)