sjat f6d589edec

Build docs site / build (push) Successful in 31s

Details

Build slides / build (push) Successful in 49s

Details

docs: split published site (docs/) from internal notes (notes/)

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>

2026-05-18 16:53:27 +02:00

2.6 KiB

Raw Blame History

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

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

2.6 KiB Raw Blame History