MakerFLOSS/docs/superpowers/plans/2026-05-10-mermaid-pipeline.md

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

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

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

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:

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

#!/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

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

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.