f6d589edec
The docs/ tree previously conflated published-site content (3 pages
were in mkdocs.yml nav) with working notes (~18 files that just sat
in the repo). Restructure so each tree means one thing:
- docs/ everything here is built and shipped to docs.makerfloss.eu.
Adds docs/presentations/ for the two Marp decks
previously living under docs/møder/.
- notes/ repo-only working material, not built. Contains
meetings/, todo/, dev/ (was docs/superpowers/), and
communications/ (the launch Facebook post).
- sandbox/ test-mermaid.md, the Marp/Mermaid pipeline sandbox.
Other touches:
- Drop "_noter" suffix on meeting filenames; drop "_presentation"
from the messaging deck's basename for symmetry with SoMe-taxonomi.
- Update CLAUDE.md and docs/index.md path references.
- Drop the now-redundant --exclude-dir=superpowers from
build-slides.sh since superpowers/ is no longer under docs/.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 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
|