mermaid-lint
Ein Mermaid-Diagramm mit Syntaxfehler zeigt auf GitHub statt der Grafik den Kasten
"Unable to render rich display". Lokal faellt das nicht auf, weil kein Werkzeug den
Block prueft. Dieser Skill schliesst die Luecke.
Wann anwenden
- Ein README oder Dokument zeigt auf GitHub einen Renderfehler statt eines Diagramms.
- Vor einer Veroeffentlichung oder einem Release mit Diagrammen in der Dokumentation.
- Nach jedem Umbau von Markdown, der Mermaid-Bloecke beruehrt.
- Flaechendeckend ueber mehrere Repos, wenn unklar ist, wo ueberall etwas kaputt ist.
Die zwei Werkzeuge
1. mermaid_lint.mjs — Syntaxpruefung ohne Browser
node mermaid_lint.mjs <repo-pfad> [...] [--json]
node mermaid_lint.mjs --from <liste.txt> [--json]
Sucht rekursiv alle .md-Dateien, extrahiert jeden ```mermaid-Block und laesst ihn
durch mermaid.parse() laufen — denselben Parser, den GitHub im Browser benutzt.
Exit 0 = alles parst, Exit 1 = mindestens ein Block defekt. Ausgabe nennt Datei,
Blocknummer, Zeile und den woertlichen Parserfehler.
--from <datei> liest eine Pfadliste, eine pro Zeile. Nutze das statt vieler Argumente:
Windows-Pfade mit Backslashes werden in der Bash-Shell stumm zerfressen
(aus D:\code\my-repo wird D:codemy-repo). Schreibe Pfade mit Forward-Slashes.
Ein einziger Prozess schafft hunderte Repos, weil Mermaid nur einmal geladen wird.
Kein Puppeteer, kein Chromium-Download.
2. readback.mjs — Beweis an der lebenden Seite
node readback.mjs <github-url> [...]
Oeffnet die Seiten im vorhandenen Edge (kein Browser-Download) und zaehlt echte
Renderfehler. Urteil je Seite: OK, DEFEKT, UNKLAR oder KEIN-MERMAID.
Drei Fallen, die diesen Skill noetig machen
GitHub rendert Mermaid in sandboxed iframes von viewscreen.githubusercontent.com.
Die Hauptseite sieht deren Inhalt nicht. Wer nur document.body.innerText oder
msedge --dump-dom auswertet, bekommt auf jeder Seite null Fehler gemeldet — auch
auf einer nachweislich kaputten. readback.mjs wertet deshalb alle Frames aus.
Ein einzelner DEFEKT-Befund ist nicht belastbar. Waehrend des Ladens zeigt GitHub
kurz einen Platzhalter, der wie ein Renderfehler aussieht. Gemessen am 2026-09-20:
dieselbe Seite meldete erst ERR=1, dann zweimal ERR=0. readback.mjs wiederholt
negative Befunde deshalb automatisch; ein OK wird nie wiederholt.
mermaid.parse() braucht ein DOM, sonst scheitert es an DOMPurify.addHook und
meldet gueltige Flowcharts faelschlich als kaputt. mermaid_lint.mjs stellt vorab
ein jsdom-Fenster bereit. Bleibt trotzdem ein Umgebungsfehler uebrig, landet er
getrennt unter envIssues und wird nicht als Syntaxfehler gezaehlt.
Immer gegen eine Negativkontrolle pruefen
Bevor du einem gruenen Ergebnis glaubst, lass das Werkzeug einmal auf einen Stand los,
von dem du weisst, dass er kaputt ist — etwa den Commit vor deinem Fix:
node readback.mjs "https://github.com/<org>/<repo>/blob/<alter-sha>/README.md"
Meldet der auch OK, misst dein Readback nichts. Genau so wurde die iframe-Falle oben
entdeckt.
Haeufige Fehlerursachen und ihre minimal-invasive Behebung
| Symptom im Parserfehler |
Ursache |
Behebung |
Expecting '+', '-', '()', 'ACTOR', got 'loop' |
Teilnehmer heisst wie ein reserviertes Wort: loop, alt, opt, par, end, critical, break, rect, note |
Alias deklarieren: participant L as Loop, Nachrichten nutzen L. Der angezeigte Name bleibt — nicht umbenennen. |
got 'PS' in einem Flowchart |
Runde Klammern im Knotenlabel |
Label quoten: A["Start (hier)"] |
Lexical error ... Unrecognized text |
Backticks oder Doppelpunkt im Label |
Label quoten, Backticks entfernen |
Expecting 'SEMI', 'NEWLINE', 'EOF' in graph/flowchart |
Note: gibt es nur in Sequenz- und Klassendiagrammen |
Hinweistext aus dem Block nehmen und als Markdown-Zeile darunter setzen, damit die Information sichtbar bleibt |
Expecting 'SOLID_OPEN_ARROW' ... got 'NEWLINE' in einem Sequenzdiagramm |
HTML-Entity im Nachrichtentext (λ, Δ, ≥). Nicht die Klammern und nicht das = brechen hier — das abschliessende ; der Entity liest der Lexer als Statement-Terminator, alles dahinter wird neue Anweisung. |
Entity durch das literale Zeichen ersetzen (λ, Δ, ≥), Text sonst unveraendert. Klammern duerfen bleiben. Zahlenwerte und ihre Schreibweise niemals veraendern. |
| Semikolon in einer Sequenznachricht |
wird als Statement-Ende gelesen |
durch - ersetzen |
In quotierten Flowchart-Labels sind Entities unproblematisch — die Regel gilt nur fuer
Sequenznachrichten. mermaid_lint.mjs meldet solche Entities als eigene [WARN]-Zeile
(Feld warnings im JSON), zusaetzlich zum Parserfehler: der Parser sagt nur
got 'NEWLINE' und nennt die Ursache nicht.
Grundsatz: minimal-invasiv. Layout, Knoten-IDs, Reihenfolge und sichtbarer Text
bleiben, soweit irgend moeglich, unveraendert. In wissenschaftlichen Repos gilt das
besonders fuer Zahlenwerte und deren Schreibweise. Bei EN/DE-Paritaet beide Fassungen
strukturgleich halten.
Ablauf ueber mehrere Repos
- Inventar per
gh repo list <org> --limit 200 --json name,isArchived,isPrivate,defaultBranchRef.
- Klone auf Remote-Stand ziehen und Divergenzen ernst nehmen. Ein Lint auf einem
veralteten Klon misst den falschen Stand. Schlaegt
git pull --ff-only fehl, pruefe
gegen origin statt gegen den Arbeitsbaum:
git archive origin/<branch> | tar -x -C <tempdir> und linte den Tempordner.
- Gleichnamige Repos verschiedener Orgs (typisch
.github) duerfen nicht auf
denselben Klon gemappt werden — sonst prueft man neunmal dasselbe Repo. Bei
Namensdopplung flach nach <org>__<repo> klonen und den frischen Stand linten.
- Vor jeder Aenderung Locks pruefen (
lock_scan.py, LOCK*.txt im Klon und am
OneDrive-Projektpfad), eigenen Lock setzen, nach dem Push wieder entfernen.
Scope lesen, nicht nur die Existenz: LOCK.team.* mit abgelaufener
expires_after ist ignorierbar; LOCK.user.zenodo-upload.txt sperrt ausschliesslich
die externe Zenodo-Schreiboperation und erlaubt Doku-Aenderungen ausdruecklich.
Ein LOCK.user.until-winners-announcement.txt (Judging) sperrt dagegen jeden Push —
dort nur lesend pruefen und den Befund als Ticket ablegen.
- Reparieren, linten bis gruen, committen,
git pull --rebase, pushen.
- Readback mit Negativkontrolle. Erst dann gilt es als erledigt.
Einrichtung
npm install mermaid jsdom playwright-core
Im Ordner der Skripte oder global; playwright-core nutzt den installierten Edge
(channel: 'msedge') und laedt keinen eigenen Browser herunter. Nur fuer den Readback
noetig — die Syntaxpruefung laeuft ohne ihn.
Verwandt
_tools/lint_mermaid.py im GithubBot: aelterer regexbasierter Linter mit --fix.
Er repariert bekannte Muster automatisch, kennt aber keine reservierten Woerter
und ersetzt diesen Skill nicht. Sinnvolle Reihenfolge: erst mermaid_lint.mjs zur
Diagnose, dann ggf. lint_mermaid.py --fix fuer die Massenmuster, dann erneut linten.
github-repo-care: Gesamtprotokoll fuer Repo-Pflege und Veroeffentlichung.
1---2name: mermaid-lint3version: 1.0.04type: tool5author: Lukas Geiger + Claude6created: 2026-09-207updated: 2026-11-098aliases: [mermaid, mermaid-fehler, diagramm-render-fehler, unable-to-render-rich-display, schaltplan-fehler]9description: "Verwenden, wenn Mermaid-Diagramme in Markdown-Dateien auf Syntaxfehler und GitHub-Renderbarkeit geprüft oder repariert werden sollen (z. B. 'Mermaid-Syntax prüfen', 'Diagramm rendert nicht auf GitHub', 'Parse error in Diagramm', /mermaid-lint). Prüft ```mermaid-Blöcke deterministisch gegen die Mermaid-Grammatik und behebt problematische Knotenlabels und Kanten. NICHT verwenden für inhaltliche Code-Reviews außerhalb von Markdown-Diagrammen."10standalone: true11anthropic_compatible: true12bach_compatible: true13bach_origin: false14category: dev15tags: [mermaid, markdown, github, readme, diagramm, lint, dokumentation]16language: de17status: active18visibility: public19dependencies: {'tools': ['node', 'git'], 'services': ['GitHub'], 'protocols': [], 'python': [], 'npm': ['mermaid', 'jsdom', 'playwright-core']}20metadata:21 source: https://skillmd.com/skills/ellmos-ai/mermaid-lint22---232425<img src="banner.png" width="100%" alt="mermaid-lint banner">2627# mermaid-lint2829Ein Mermaid-Diagramm mit Syntaxfehler zeigt auf GitHub statt der Grafik den Kasten30**"Unable to render rich display"**. Lokal faellt das nicht auf, weil kein Werkzeug den31Block prueft. Dieser Skill schliesst die Luecke.3233## Wann anwenden3435- Ein README oder Dokument zeigt auf GitHub einen Renderfehler statt eines Diagramms.36- Vor einer Veroeffentlichung oder einem Release mit Diagrammen in der Dokumentation.37- Nach jedem Umbau von Markdown, der Mermaid-Bloecke beruehrt.38- Flaechendeckend ueber mehrere Repos, wenn unklar ist, wo ueberall etwas kaputt ist.3940## Die zwei Werkzeuge4142### 1. `mermaid_lint.mjs` — Syntaxpruefung ohne Browser4344```45node mermaid_lint.mjs <repo-pfad> [...] [--json]46node mermaid_lint.mjs --from <liste.txt> [--json]47```4849Sucht rekursiv alle `.md`-Dateien, extrahiert jeden ```mermaid-Block und laesst ihn50durch `mermaid.parse()` laufen — **denselben Parser, den GitHub im Browser benutzt**.51Exit 0 = alles parst, Exit 1 = mindestens ein Block defekt. Ausgabe nennt Datei,52Blocknummer, Zeile und den woertlichen Parserfehler.5354`--from <datei>` liest eine Pfadliste, eine pro Zeile. Nutze das statt vieler Argumente:55Windows-Pfade mit Backslashes werden in der Bash-Shell stumm zerfressen56(aus `D:\code\my-repo` wird `D:codemy-repo`). Schreibe Pfade mit Forward-Slashes.5758Ein einziger Prozess schafft hunderte Repos, weil Mermaid nur einmal geladen wird.59Kein Puppeteer, kein Chromium-Download.6061### 2. `readback.mjs` — Beweis an der lebenden Seite6263```64node readback.mjs <github-url> [...]65```6667Oeffnet die Seiten im vorhandenen Edge (kein Browser-Download) und zaehlt echte68Renderfehler. Urteil je Seite: `OK`, `DEFEKT`, `UNKLAR` oder `KEIN-MERMAID`.6970## Drei Fallen, die diesen Skill noetig machen7172**GitHub rendert Mermaid in sandboxed iframes** von `viewscreen.githubusercontent.com`.73Die Hauptseite sieht deren Inhalt nicht. Wer nur `document.body.innerText` oder74`msedge --dump-dom` auswertet, bekommt auf **jeder** Seite null Fehler gemeldet — auch75auf einer nachweislich kaputten. `readback.mjs` wertet deshalb alle Frames aus.7677**Ein einzelner DEFEKT-Befund ist nicht belastbar.** Waehrend des Ladens zeigt GitHub78kurz einen Platzhalter, der wie ein Renderfehler aussieht. Gemessen am 2026-09-20:79dieselbe Seite meldete erst `ERR=1`, dann zweimal `ERR=0`. `readback.mjs` wiederholt80negative Befunde deshalb automatisch; ein `OK` wird nie wiederholt.8182**`mermaid.parse()` braucht ein DOM**, sonst scheitert es an `DOMPurify.addHook` und83meldet gueltige Flowcharts faelschlich als kaputt. `mermaid_lint.mjs` stellt vorab84ein jsdom-Fenster bereit. Bleibt trotzdem ein Umgebungsfehler uebrig, landet er85getrennt unter `envIssues` und wird **nicht** als Syntaxfehler gezaehlt.8687## Immer gegen eine Negativkontrolle pruefen8889Bevor du einem gruenen Ergebnis glaubst, lass das Werkzeug einmal auf einen Stand los,90von dem du weisst, dass er kaputt ist — etwa den Commit vor deinem Fix:9192```93node readback.mjs "https://github.com/<org>/<repo>/blob/<alter-sha>/README.md"94```9596Meldet der auch `OK`, misst dein Readback nichts. Genau so wurde die iframe-Falle oben97entdeckt.9899## Haeufige Fehlerursachen und ihre minimal-invasive Behebung100101| Symptom im Parserfehler | Ursache | Behebung |102|---|---|---|103| `Expecting '+', '-', '()', 'ACTOR', got 'loop'` | Teilnehmer heisst wie ein reserviertes Wort: `loop`, `alt`, `opt`, `par`, `end`, `critical`, `break`, `rect`, `note` | Alias deklarieren: `participant L as Loop`, Nachrichten nutzen `L`. Der **angezeigte Name bleibt** — nicht umbenennen. |104| `got 'PS'` in einem Flowchart | Runde Klammern im Knotenlabel | Label quoten: `A["Start (hier)"]` |105| `Lexical error ... Unrecognized text` | Backticks oder Doppelpunkt im Label | Label quoten, Backticks entfernen |106| `Expecting 'SEMI', 'NEWLINE', 'EOF'` in `graph`/`flowchart` | `Note:` gibt es nur in Sequenz- und Klassendiagrammen | Hinweistext aus dem Block nehmen und als Markdown-Zeile darunter setzen, damit die Information sichtbar bleibt |107| `Expecting 'SOLID_OPEN_ARROW' ... got 'NEWLINE'` in einem Sequenzdiagramm | **HTML-Entity** im Nachrichtentext (`λ`, `Δ`, `≥`). Nicht die Klammern und nicht das `=` brechen hier — das abschliessende `;` der Entity liest der Lexer als Statement-Terminator, alles dahinter wird neue Anweisung. | Entity durch das literale Zeichen ersetzen (λ, Δ, ≥), Text sonst unveraendert. Klammern duerfen bleiben. Zahlenwerte und ihre Schreibweise niemals veraendern. |108| Semikolon in einer Sequenznachricht | wird als Statement-Ende gelesen | durch ` - ` ersetzen |109110In **quotierten Flowchart-Labels** sind Entities unproblematisch — die Regel gilt nur fuer111Sequenznachrichten. `mermaid_lint.mjs` meldet solche Entities als eigene `[WARN]`-Zeile112(Feld `warnings` im JSON), zusaetzlich zum Parserfehler: der Parser sagt nur113`got 'NEWLINE'` und nennt die Ursache nicht.114115**Grundsatz:** minimal-invasiv. Layout, Knoten-IDs, Reihenfolge und sichtbarer Text116bleiben, soweit irgend moeglich, unveraendert. In wissenschaftlichen Repos gilt das117besonders fuer Zahlenwerte und deren Schreibweise. Bei EN/DE-Paritaet beide Fassungen118strukturgleich halten.119120## Ablauf ueber mehrere Repos1211221. Inventar per `gh repo list <org> --limit 200 --json name,isArchived,isPrivate,defaultBranchRef`.1232. Klone **auf Remote-Stand ziehen** und Divergenzen ernst nehmen. Ein Lint auf einem124 veralteten Klon misst den falschen Stand. Schlaegt `git pull --ff-only` fehl, pruefe125 gegen `origin` statt gegen den Arbeitsbaum:126 `git archive origin/<branch> | tar -x -C <tempdir>` und linte den Tempordner.1273. **Gleichnamige Repos verschiedener Orgs** (typisch `.github`) duerfen nicht auf128 denselben Klon gemappt werden — sonst prueft man neunmal dasselbe Repo. Bei129 Namensdopplung flach nach `<org>__<repo>` klonen und den frischen Stand linten.1304. Vor jeder Aenderung Locks pruefen (`lock_scan.py`, `LOCK*.txt` im Klon **und** am131 OneDrive-Projektpfad), eigenen Lock setzen, nach dem Push wieder entfernen.132 **Scope lesen, nicht nur die Existenz:** `LOCK.team.*` mit abgelaufener133 `expires_after` ist ignorierbar; `LOCK.user.zenodo-upload.txt` sperrt ausschliesslich134 die externe Zenodo-Schreiboperation und erlaubt Doku-Aenderungen ausdruecklich.135 Ein `LOCK.user.until-winners-announcement.txt` (Judging) sperrt dagegen jeden Push —136 dort nur lesend pruefen und den Befund als Ticket ablegen.1375. Reparieren, linten bis gruen, committen, `git pull --rebase`, pushen.1386. Readback mit Negativkontrolle. Erst dann gilt es als erledigt.139140## Einrichtung141142```143npm install mermaid jsdom playwright-core144```145146Im Ordner der Skripte oder global; `playwright-core` nutzt den installierten Edge147(`channel: 'msedge'`) und laedt keinen eigenen Browser herunter. Nur fuer den Readback148noetig — die Syntaxpruefung laeuft ohne ihn.149150## Verwandt151152- `_tools/lint_mermaid.py` im GithubBot: aelterer regexbasierter Linter mit `--fix`.153 Er repariert bekannte Muster automatisch, **kennt aber keine reservierten Woerter**154 und ersetzt diesen Skill nicht. Sinnvolle Reihenfolge: erst `mermaid_lint.mjs` zur155 Diagnose, dann ggf. `lint_mermaid.py --fix` fuer die Massenmuster, dann erneut linten.156- `github-repo-care`: Gesamtprotokoll fuer Repo-Pflege und Veroeffentlichung.