mermaid-lint
Findet und behebt Mermaid-Diagramme, die GitHub nicht rendert ("Unable to render rich display"). Prueft jeden ```mermaid-Block mit dem echten Mermaid-Parser ohne Browser und belegt das Ergebnis danach
SKILL.mdskills/dev/mermaid-lint/SKILL.md
GitHub<img src="banner.png" width="100%" alt="mermaid-lint banner">
1.
2.
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-onlyfehl, pruefe gegenoriginstatt 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*.txtim Klon und am OneDrive-Projektpfad), eigenen Lock setzen, nach dem Push wieder entfernen. Scope lesen, nicht nur die Existenz:LOCK.team.*mit abgelaufenerexpires_afterist ignorierbar;LOCK.user.zenodo-upload.txtsperrt ausschliesslich die externe Zenodo-Schreiboperation und erlaubt Doku-Aenderungen ausdruecklich. EinLOCK.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.pyim GithubBot: aelterer regexbasierter Linter mit--fix. Er repariert bekannte Muster automatisch, kennt aber keine reservierten Woerter und ersetzt diesen Skill nicht. Sinnvolle Reihenfolge: erstmermaid_lint.mjszur Diagnose, dann ggf.lint_mermaid.py --fixfuer die Massenmuster, dann erneut linten.github-repo-care: Gesamtprotokoll fuer Repo-Pflege und Veroeffentlichung.