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

Mermaid + Marp Pipeline Design

Date: 2026-05-10 Status: Approved

Goal

Enable Mermaid diagrams in Marp presentations without any per-file manual steps for authors. A push to the repo triggers the existing webhook CI, which builds the slides and serves them at slides.makerfloss.eu.

Context

• Webhook CI is live: push → build-slides.sh → slides/ served at slides.makerfloss.eu
• build-slides.sh already passes --html to marp (raw HTML in markdown is allowed)
• Marp emits fenced mermaid blocks as <pre><code class="language-mermaid">…</code></pre>
• A previous attempt (2459b4c) used a custom marp.config.mjs but failed: it overrode rules.code instead of rules.fence, so mermaid blocks were never transformed. That approach also required npm install on the server. It was reverted.

Approach: HTML post-processing in build-slides.sh

After the marp build, loop over every slides/*.html. For each file that contains class="language-mermaid", inject the following snippet before </body>:

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

Injection uses python3 (reliable string replacement, avoids sed quoting issues; python3 is available on any Debian-based host).

Why this approach

• Zero server changes required
• Zero per-file authoring requirements — authors write normal ```mermaid fences
• Works with all three build paths in build-slides.sh (npx / global marp / Docker)
• Only injects into files that actually contain mermaid blocks

Constraints

• Mermaid theme hardcoded to 'dark' — all current presentations use the dark gaia theme
• Requires browser with ES module support (all modern browsers qualify)
• Mermaid rendering is client-side; diagrams will not appear in PDF exports

Changes

File	Change
build-slides.sh	Add post-processing loop after marp build
docs/test-mermaid.md	New test presentation with mermaid diagram

Test plan

1. Push docs/test-mermaid.md to main
2. Webhook triggers; wait for build
3. Verify slides.makerfloss.eu/test-mermaid.html is listed on the index
4. Open the slide and confirm the mermaid diagram renders (not a code block)
5. Verify existing slides (messaging-presentation, SoMe-taxonomi, labdesign) are unaffected