From f20a52268abaee061e5c882986ab3224126f094a Mon Sep 17 00:00:00 2001
From: sjat <sjat@fisi.nyumbani.baobab.band>
Date: Sun, 10 May 2026 17:39:35 +0200
Subject: [PATCH] docs: add mermaid pipeline implementation plan

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../plans/2026-05-10-mermaid-pipeline.md      | 218 ++++++++++++++++++
 1 file changed, 218 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-10-mermaid-pipeline.md

diff --git a/docs/superpowers/plans/2026-05-10-mermaid-pipeline.md b/docs/superpowers/plans/2026-05-10-mermaid-pipeline.md
new file mode 100644
index 0000000..0fa0a2c
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-10-mermaid-pipeline.md
@@ -0,0 +1,218 @@
+# 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.