sjat/MakerFLOSS
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: sjat:7b045979a5921168347f1b534c2964313127c08b
Branches Tags
sjat:main
..
compare: sjat:4f4e17d0bf3816f32e761478ad0b98684598bf5c
Branches Tags
sjat:main

No commits in common. "7b045979a5921168347f1b534c2964313127c08b" and "4f4e17d0bf3816f32e761478ad0b98684598bf5c" have entirely different histories.
7b045979a5 ... 4f4e17d0bf

3 changed files with 0 additions and 316 deletions
Show stats Expand all files Collapse all files

218
docs/superpowers/plans/2026-05-10-mermaid-pipeline.md
View file

@ -1,218 +0,0 @@
# 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.

63
docs/superpowers/specs/2026-05-10-mermaid-pipeline-design.md
View file

@ -1,63 +0,0 @@
# 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

35
docs/test-mermaid.md
View file

@ -1,35 +0,0 @@
---
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