Mermaid-Gantt-Diagramme: Syntax, Fallstricke und der Weg zurück in einen Editor

Die Syntax in einem Durchgang

Ein Gantt-Block beginnt mit dem Schlüsselwort gantt und einigen Kopfzeilen, danach folgen section-Überschriften mit Vorgangszeilen darunter. Die Einrückung ist Konvention und nicht Grammatik, Mermaid liest den Block auch ohne sie.

Eine Vorgangszeile besteht aus einem Namen, einem Doppelpunkt und dann kommagetrennten Feldern:

Name des Vorgangs :tag, id, start, dauer

• Tags, beliebig viele aus done, active, crit und milestone, in beliebiger Reihenfolge. Optional.
• id, ein einzelnes Wort ohne Leerzeichen, nur nötig, wenn sich etwas anderes über after auf diesen Vorgang bezieht.
• start, ein Datum, oder after eineId, oder ganz weggelassen, um an den Vorgang darüber anzuschließen.
• dauer, 5d, 2w, oder ein zweites absolutes Datum.

Wissenswerte Kopfzeilen: dateFormat (wie die Daten in Ihrer Datei geschrieben sind), excludes weekends, title und axisFormat (wie die Achse beschriftet wird, in strftime-Codes). Die Felder werden nach ihrer Form erkannt und nicht streng nach ihrer Position, deshalb funktionieren :done, spec, 2026-03-02, 5d und :spec, done, 2026-03-02, 5d gleichermaßen.

Ein Beispiel, das Sie in eine README einfügen können

Ein vollständiger, gültiger Block für eine reale Aufgabe: die Ablösung der internen Zeiterfassungs-API eines mittelständischen Unternehmens, Version 1 auf Version 2. Er nutzt Abschnitte, absolute Daten, after-Ketten, alle Tags, einen Meilenstein sowie ausgeschlossene Wochenenden und Feiertage. Fügen Sie ihn in einen Codeblock mit der Sprache mermaid in einer beliebigen Markdown-Datei auf GitHub ein, und er wird gerendert.

gantt
    title Abloesung der Zeiterfassungs-API (v1 auf v2)
    dateFormat YYYY-MM-DD
    axisFormat %d.%m.
    excludes weekends 2026-04-03 2026-04-06 2026-05-01

    section Analyse
    Bestand v1 erheben        :done, best, 2026-03-02, 5d
    OpenAPI-Spezifikation     :done, spec, after best, 4d
    Spezifikation abstimmen   :active, abst, after spec, 2d

    section Datenschutz und Mitbestimmung
    Datenschutz-Folgenabschaetzung  :crit, dsfa, after abst, 8d
    Betriebsvereinbarung verhandeln :crit, bv, after dsfa, 15d
    Betriebsvereinbarung unterzeichnet :milestone, bvm, 2026-04-24, 0d

    section Umsetzung
    Authentifizierungsdienst  :auth, after bvm, 10d
    Fachendpunkte             :fach, after auth, 12d
    Client-SDK neu erzeugen   :sdk, after fach, 3d

    section Umstellung
    Testbetrieb               :test, after sdk, 5d
    Abschaltung v1            :ab, after test, 2w

Referenz der Vorgangszeile

Jedes Feld, was es bewirkt und wie es in der Praxis aussieht.

Vier Dinge, über die Sie stolpern werden

1. Dauern schließen den Starttag ein. 5d ab Montag, dem 5., läuft bis Freitag, den 9., nicht bis zum 10. Ein Fehler um eins verschiebt hier jeden Vorgang der Datei und wird trotzdem tadellos gerendert, das ist die schlimmste denkbare Fehlerart, weil nichts kaputt aussieht.

2. after zusammen mit excludes weekends ist die eigentliche Fehlerquelle. Endet ein Vorgänger an einem Freitag, beginnt sein Nachfolger am Montag, nicht am Samstag. Jedes Werkzeug, das after durch Addition eines einzelnen Kalendertages auflöst, legt Vorgänge klammheimlich auf Wochenenden in einer Datei, die genau das verbietet, und ab dort läuft jedes weitere Datum weg. Unseres tat das kurzzeitig. Die Korrektur führt die Rechnung über den Arbeitskalender, damit der Import mit dem übereinstimmt, was Mermaid zeichnet; der absichernde Test prüft die Eigenschaft statt bestimmter Daten: Kein abgeleitetes Anfangs- oder Enddatum darf auf einen ausgeschlossenen Tag fallen. Daten, die Sie selbst getippt haben, bleiben dagegen stehen, wo Sie sie hingeschrieben haben, Wochenende hin oder her, das ausdrückliche Datum einer Autorin stillschweigend zu verschieben ist die falsche Art von Hilfsbereitschaft.

3. Es gibt keine Maskierung. Ein Doppelpunkt beginnt die Feldliste und ein Komma trennt die Felder, aus Phase 2: Entwurf, Prüfung wird also ein Vorgang namens „Phase 2“ mit unsinnigen Feldern. Halten Sie Doppelpunkte, Kommas und Semikolons aus Vorgangsnamen heraus; beim Export ersetzen wir sie durch Leerzeichen, statt eine Zeile auszugeben, die sich nicht lesen lässt.

4. Eine unlesbare Dauer wird stillschweigend null. Schreiben Sie 3dd, erhalten Sie einen Balken der Länge null statt einer Fehlermeldung. Suchen Sie nach jeder größeren Änderung gezielt nach unsichtbaren Vorgängen.

Die Grenzen eines Diagrammformats

Mermaid gantt ist eine Darstellungssprache und keine Terminplanungsmaschine. Der Unterschied fällt in dem Moment auf, in dem das Diagramm eine Frage beantworten statt eine Antwort bebildern soll.

• Keine Ressourcen. Kein Feld für die zuständige Person, keine Kosten, kein Aufwand. Sie können in Mermaid niemanden überlasten, weil Mermaid nicht weiß, dass es Menschen gibt.
• Kein Puffer und kein berechneter kritischer Pfad. crit ist eine Farbe, die Sie von Hand vergeben. Nichts läuft das Abhängigkeitsnetz ab, nichts rechnet frühe und späte Lagen aus, nichts sagt Ihnen, welche Kette das Enddatum bestimmt. Ein Diagramm, in dem jeder Balken crit trägt, ist genauso gültig wie eines, in dem es keiner tut.
• Kein Basisplan. Es gibt keine Stelle, an der stünde, was der Plan im vergangenen Monat gesagt hat, also auch keine Abweichung und keinen messbaren Verzug.
• Nur Ende-Anfang. after ist eine EA-Verknüpfung ohne Zeitabstand. Anfang-Anfang, Ende-Ende, Anfang-Ende und jeder Zeitabstand haben keinen Platz. Echte Pläne stecken voller Sätze wie „der Test beginnt drei Tage nach dem Beginn der Entwicklung“, in Mermaid wird daraus ein fest eingetragenes Datum, und die Verknüpfung ist verschwunden.
• Kein Fortschritt in Prozent. Ein Vorgang bei 40 Prozent und einer bei 90 Prozent sind beide schlicht active.
• Flache Abschnitte. Keine verschachtelten Gruppen, eine Gliederung mit mehr als einer Ebene wird beim Einlesen also flach.

Nichts davon macht Mermaid zu einem schlechten Format. Es macht es zu einem Veröffentlichungsformat, gut darin, einen Terminplan zu zeigen, ungeeignet, einen herzuleiten. Genau deshalb zählt der Rückweg.

Visuell bearbeiten, dann den Text zurückkopieren

Mermaid rendern können viele Werkzeuge. Gefehlt hat die Gegenrichtung, Balken ziehen und die Syntax wieder herausbekommen.

1. Fügen Sie Ihr Diagramm über ✨ In Gantt einfügen ein oder öffnen Sie die Datei über 📂 Öffnen, eine .mmd-Datei oder eine .md-Datei mit eingebettetem Block, beides funktioniert. Ein Gantt-Block wird an seinem Inhalt erkannt, nicht an der Dateiendung.
2. Ziehen, verknüpfen und umdatieren Sie wie in jedem anderen Diagramm. excludes weekends schaltet den Arbeitskalender ein, sodass die erzeugten Termine zu der Datei passen, aus der sie stammen; unter Kalender ergänzen Sie die Feiertage Ihres Bundeslandes.
3. Setzen Sie den Haken bei Kritischer Pfad. Die schraffierten Balken sind das berechnete Ergebnis, und nicht das, was in der Datei behauptet wurde.
4. Über ⬇ Export ▸ 🧜 Mermaid-Gantt (Text) erhalten Sie den aktualisierten Text, entweder über In die Zwischenablage kopieren oder als .mmd herunterladen. Zurück in die README einfügen, Diff einchecken, fertig.

Der Hin- und Rückweg verliert etwas, aber auf bekannte, langweilige Weise. Der Fortschritt wird beim Export als 100 Prozent auf done und alles zwischen 1 und 99 Prozent auf active abgebildet; beim Import kommt active als 50 Prozent zurück, eine Schätzung, auf die Sie hingewiesen werden, statt sie später in einem Statusbericht zu entdecken. Verknüpfungen, die sich nicht als after schreiben lassen, alles mit Zeitabstand und jede AA-, EE- oder AE-Beziehung, , fallen auf feste Termine zurück. Die bleiben korrekt, hören aber auf, pflegbar zu sein.

Eine Asymmetrie ist Absicht und kein Fehler: crit wird exportiert, aber niemals importiert. Auf dem Weg hinaus ist der Wert abgeleitet, der Editor hat den kritischen Pfad aus dem Abhängigkeitsnetz berechnet, das Tag ist im Moment des Schreibens also wahr. Auf dem Weg hinein ist es ein Wort, das jemand in eine womöglich wochenalte Datei getippt hat; ihm zu vertrauen hieße, eine unkritische Kette rot einzufärben. Also wird es geschrieben und danach ignoriert: Der kritische Pfad, den Sie nach einem Import sehen, ist neu berechnet und nicht behauptet.

Für alle, die Terminpläne mit einem Sprachmodell entwerfen, gibt es einen angenehmen Nebeneffekt: Lassen Sie sich Mermaid-Gantt-Syntax ausgeben, fügen Sie die Antwort ein, und Sie haben ein echtes, bearbeitbares Diagramm mit berechnetem kritischem Pfad, ohne API-Schlüssel und ohne Server.

Häufige Fragen

Passende Vorlagen

• Projektmanagement

Passend dazu

• Die vier Abhängigkeitsarten
• Der kritische Pfad
• Was ist ein Gantt-Diagramm?
• Zurück zu den Ratgebern

Dieser Artikel ist auch auf Englisch verfügbar.