--- name: mermaid-lint version: 1.0.0 type: tool author: Lukas Geiger + Claude created: 2026-09-20 updated: 2026-09-20 aliases: [mermaid, mermaid-fehler, diagramm-render-fehler, unable-to-render-rich-display, schaltplan-fehler] description: 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 an der lebenden GitHub-Seite. standalone: true anthropic_compatible: true bach_compatible: true bach_origin: false category: dev tags: [mermaid, markdown, github, readme, diagramm, lint, dokumentation] language: de status: active visibility: public dependencies: {'tools': ['node', 'git'], 'services': ['GitHub'], 'protocols': [], 'python': [], 'npm': ['mermaid', 'jsdom', 'playwright-core']} --- # 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 [...] [--json] node mermaid_lint.mjs --from [--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 ` 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 [...] ``` 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///blob//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 1. Inventar per `gh repo list --limit 200 --json name,isArchived,isPrivate,defaultBranchRef`. 2. 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/ | tar -x -C ` und linte den Tempordner. 3. **Gleichnamige Repos verschiedener Orgs** (typisch `.github`) duerfen nicht auf denselben Klon gemappt werden — sonst prueft man neunmal dasselbe Repo. Bei Namensdopplung flach nach `__` klonen und den frischen Stand linten. 4. 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. 5. Reparieren, linten bis gruen, committen, `git pull --rebase`, pushen. 6. 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.