# 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>`:

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