# Mermaid Pipeline Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make mermaid diagrams render automatically in any Marp slide pushed to the repo, with zero per-file author effort.

**Architecture:** Post-process generated HTML files in `build-slides.sh` — after marp builds slides, a python3 snippet injects mermaid.js into any HTML that contains `class="language-mermaid"` blocks. Authors write normal fenced mermaid blocks; the pipeline handles the rest.

**Tech Stack:** bash, python3 (stdlib only), mermaid.js v11 from CDN

---

### Task 1: Create test slide

**Files:**
- Create: `docs/test-mermaid.md`

- [ ] **Step 1: Create `docs/test-mermaid.md`**

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

# Mermaid Pipeline Test

Validating mermaid diagram rendering in Marp slides.

MakerFLOSS · May 2026

---

## Build Pipeline

```mermaid
graph LR
    A[Write Markdown] --> B[git push]
    B --> C[Forgejo webhook]
    C --> D[build-slides.sh]
    D --> E[mermaid inject]
    E --> F[slides.makerfloss.eu]
```

---

## Regular Slide

No diagram here — confirms regular content is unaffected.

- Bullet one
- Bullet two
- Bullet three
````

- [ ] **Step 2: Commit**

```bash
git add docs/test-mermaid.md
git commit -m "test: add mermaid pipeline test slide"
```

---

### Task 2: Push test slide and confirm mermaid is broken

**Files:** (none modified)

- [ ] **Step 1: Push to trigger CI**

```bash
git push origin main
```

- [ ] **Step 2: Wait ~30 seconds, then check the index**

Open `https://slides.makerfloss.eu/` in a browser. `test-mermaid` should appear in the list.

- [ ] **Step 3: Confirm mermaid is NOT rendering**

Open `https://slides.makerfloss.eu/test-mermaid.html`.

Navigate to the "Build Pipeline" slide. Expected: the mermaid block renders as a grey code block, **not** a diagram. This is the failing state we are about to fix.

---

### Task 3: Add mermaid post-processing to `build-slides.sh`

**Files:**
- Modify: `build-slides.sh`

The current file ends with:

```bash
echo "Done — slides in $OUTPUT_DIR/"
```

- [ ] **Step 1: Open `build-slides.sh` and replace the final `echo` with the full post-processing block**

The complete file after editing (replace everything from the final `echo "Done..."` line onwards):

```bash
#!/usr/bin/env bash
set -euo pipefail

REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
OUTPUT_DIR="$REPO_ROOT/slides"
mkdir -p "$OUTPUT_DIR"

# Find all markdown files with marp: true frontmatter
SLIDES=()
while IFS= read -r f; do
  SLIDES+=("$f")
done < <(grep -rl "^marp: true" "$REPO_ROOT/docs" --include="*.md" 2>/dev/null || true)

if [ ${#SLIDES[@]} -eq 0 ]; then
  echo "No marp presentations found in docs/."
  exit 0
fi

echo "Found ${#SLIDES[@]} presentation(s):"
printf '  %s\n' "${SLIDES[@]}"

if command -v marp &>/dev/null; then
  marp --html --output "$OUTPUT_DIR/" "${SLIDES[@]}"
else
  echo "marp not found locally — using Docker (marpteam/marp-cli)..."
  REL_SLIDES=()
  for f in "${SLIDES[@]}"; do
    REL_SLIDES+=("${f#"$REPO_ROOT"/}")
  done
  docker run --rm \
    -v "$REPO_ROOT":/home/marp/app:ro \
    -v "$OUTPUT_DIR":/home/marp/output \
    marpteam/marp-cli --html --output /home/marp/output "${REL_SLIDES[@]}"
fi

# Inject mermaid.js into any HTML that contains mermaid code blocks.
# Marp emits fenced mermaid blocks as <pre><code class="language-mermaid">.
# The script finds those elements, replaces them with <div class="mermaid">,
# then loads and runs mermaid.js from CDN.
inject_mermaid() {
  local html_file="$1"
  python3 - "$html_file" << 'PYEOF'
import sys

path = sys.argv[1]
snippet = """\
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
document.querySelectorAll('code.language-mermaid').forEach(el => {
  const div = document.createElement('div');
  div.className = 'mermaid';
  div.textContent = el.textContent;
  el.closest('pre').replaceWith(div);
});
mermaid.initialize({ startOnLoad: false, theme: 'dark' });
await mermaid.run();
</script>"""

content = open(path).read()
open(path, 'w').write(content.replace('</body>', snippet + '\n</body>', 1))
PYEOF
}

if command -v python3 &>/dev/null; then
  for html_file in "$OUTPUT_DIR"/*.html; do
    [ -f "$html_file" ] || continue
    if grep -q 'class="language-mermaid"' "$html_file"; then
      inject_mermaid "$html_file"
      echo "  Injected mermaid.js into $(basename "$html_file")"
    fi
  done
else
  echo "Warning: python3 not found — skipping mermaid injection"
fi

echo "Done — slides in $OUTPUT_DIR/"
```

- [ ] **Step 2: Commit**

```bash
git add build-slides.sh
git commit -m "feat: inject mermaid.js into slides that use it"
```

---

### Task 4: Push, verify mermaid renders, verify no regressions

**Files:** (none modified)

- [ ] **Step 1: Push**

```bash
git push origin main
```

- [ ] **Step 2: Wait ~30 seconds, then open the test slide**

Open `https://slides.makerfloss.eu/test-mermaid.html`.

Navigate to the "Build Pipeline" slide.

Expected: a rendered flowchart with boxes and arrows — **not** a code block.

- [ ] **Step 3: Verify existing slides are unaffected**

Open `https://slides.makerfloss.eu/2026-05-11_messaging-presentation.html` and page through it. Expected: renders normally, no JS errors in browser console.

Open `https://slides.makerfloss.eu/labdesign.html` and navigate to the "Lab Diagram" slide. Expected: mermaid diagram now renders there too (it already had mermaid blocks).

- [ ] **Step 4: Verify the index page still lists all slides**

Open `https://slides.makerfloss.eu/`. Expected: all slides including `test-mermaid` are listed.