So steuern Sie das Diagramm-Layout in Mermaid

In Mermaid 12 legt der Konfigurationsschlüssel layout die Layout-Engine fest: ELK ist für die meisten Graphdiagramme der Standard. Mit layout: dagre im Front Matter oder in mermaid.initialize() erhalten Sie die vorherige Engine zurück.

Sie haben ein Upgrade durchgeführt und die Dokumentationsseite neu gebaut, und plötzlich hat ein Flowchart, das niemand angefasst hat, eine andere Form und andere Farben. Ein diagrammtypspezifischer Abschnitt wie flowchart: { defaultRenderer: ... } aus einer älteren Antwort behebt das nicht.

Dieser Artikel erklärt, was sich geändert hat, wo Sie das Layout festlegen, welche Einstellung Vorrang hat, wie Sie ELK feinabstimmen und warum ein Zurücksetzen scheinbar keine Wirkung zeigen kann. Grundlagen zu Flowcharts finden Sie unter Flowcharts für Workflows erstellen.

Was hat sich in Mermaid 12 geändert?

Ab Mermaid 12 wird ein Diagramm, das kein Layout angibt, von ELK statt von dagre angeordnet. Ein unverändertes Diagramm kann nach dem Upgrade also eine andere Form haben. Die Konfigurationsseite zu Layouts nennt sieben Diagrammtypen, die jetzt standardmäßig ELK verwenden: Flowchart, State, Class, Entity Relationship, Requirement, Use Case und Agentflow. ELK wird mit dem Hauptpaket ausgeliefert und registriert sich automatisch. Mindmaps verwenden weiterhin standardmäßig cose-bilkent, und tidy-tree stammt aus dem separaten Paket @mermaid-js/layout-tidy-tree.

Die Release Notes zu mermaid@12.0.0 beschreiben außerdem eine zweite Änderung: Das Standard-Theme ist jetzt redux-color und der Standard-Look jetzt neo – und zwar für die breitere Auswahl an Diagrammtypen, die in den diagrammspezifischen Standardwerten auf der Theming-Seite aufgeführt sind. Ein Diagramm in v12 kann also aus zwei unterschiedlichen Gründen anders aussehen: Die Layout-Engine hat sich geändert, und Theme und Look haben sich geändert.

Wo legen Sie das Layout fest: Front Matter, initialize() oder typspezifische Konfiguration?

Sie können das Mermaid-Layout für ein einzelnes Diagramm oder für alle Diagramme einer Website festlegen. Theme und Look lassen sich zudem auf einen einzelnen Diagrammtyp beschränken. Bei widersprüchlichen Einstellungen gewinnt die spezifischste.

Laut den Release Notes zu 12.0.0 gilt folgende Auflösungsreihenfolge: zuerst Front Matter oder Direktive, dann initialize(), dann der Standardwert des Diagrammtyps und zuletzt der globale Standardwert.

So setzen Sie ein einzelnes Diagramm vollständig zurück:

---
config:
  layout: dagre
  theme: default
  look: classic
---
flowchart LR
  Request --> Auth{Valid token?}
  Auth -->|yes| Handler
  Auth -->|no| Reject

Seitenweit ändert der erste der folgenden Aufrufe nur die Engine, die neuen Farben bleiben also erhalten. Der zweite Aufruf stellt die vollständige Darstellung wie vor Version 12 wieder her:

mermaid.initialize({ layout: 'dagre' });

mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' });

Mermaid 12 erlaubt es außerdem, theme, look und layout innerhalb des Konfigurationsabschnitts eines Diagrammtyps auf diesen Typ zu beschränken. Ein so beschränkter Wert hat Vorrang vor einem globalen Wert, der an derselben Stelle gesetzt wird. Um alle Diagramme auf dagre umzustellen, das alte Erscheinungsbild aber nur für Class-Diagramme wiederherzustellen, belassen Sie layout auf der obersten Ebene und setzen theme und look im Abschnitt class, wie auf der Seite zu Class-Diagrammen gezeigt:

mermaid.initialize({
  layout: 'dagre',
  class: { theme: 'default', look: 'classic' },
});

Front Matter hat immer Vorrang vor mermaid.initialize(). Angenommen, eine Website setzt layout: 'dagre' seitenweit, und ein Diagramm deklariert layout: elk in seinem Front Matter. Dann wird dieses Diagramm mit ELK gerendert.

Wann hilft das ELK-Layout in Mermaid, und wie stimmen Sie es ab?

Verwenden Sie ELK für große oder dicht gedrängte Diagramme. Bleiben Sie bei dagre, wenn ein kleines Diagramm bereits gut aussieht. Die Mermaid-Dokumentation empfiehlt ELK für große, komplexe Graphen, während dagre als bewährtes Layered-Layout weiterhin verfügbar ist. Wenn Ihre Diagramme vor dem Upgrade gut dargestellt wurden, ist die Rückkehr zu dagre eine vernünftige Wahl.

Der Layout-Abschnitt der Syntaxreferenz dokumentiert mehrere Schlüssel zur Feinabstimmung von ELK, darunter die folgenden: mergeEdges fasst parallele Kanten zusammen. nodePlacementStrategy akzeptiert SIMPLE, NETWORK_SIMPLEX, LINEAR_SEGMENTS oder BRANDES_KOEPF, wobei BRANDES_KOEPF unter dem Preset default der Standardwert ist. nodePlacementAlignment legt die Brandes-Köpf-Ausrichtung fest (zum Beispiel BALANCED oder NONE). Lassen Sie den Schlüssel weg, ergibt sich die Ausrichtung aus dem Preset.

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: NETWORK_SIMPLEX
---
flowchart TD
  Build --> Test --> Deploy
  Build --> Lint --> Deploy

Auch Diagramme, die bereits vor v12 ELK verwendet haben, können sich ändern, da nun die ausbalancierte Brandes-Köpf-Platzierung der Standard ist. Das Schema der ELK-Presets führt vier preset-Werte auf: legacy, default, modelOrder und depthFirst. Es beschreibt depthFirst als den bisherigen Standard und gibt an, dass legacy die Darstellung von ELK aus der Zeit vor Einführung der Presets reproduziert.

Auch innerhalb von 12.x hat sich die Ausgabe von ELK verändert:

• Mermaid 12.1.0 hat orientFeedbackEdges eingeführt, standardmäßig aktiviert. Eine Kante, die von einem Knoten, den ein Subgraph speist, zurück in diesen Subgraphen führt, wird jetzt stromabwärts geführt statt um den Subgraphen herum.
• Mermaid 12.2.0 verhindert, dass ELK ein Kantenende begradigt, wenn dadurch ein Label über einer anderen Kante zu liegen käme.

config:
  layout: elk
  elk:
    preset: legacy
    orientFeedbackEdges: false

Welche ELK-Varianten und subgraphspezifischen Algorithmen stehen zur Verfügung?

Neben layout: elk nennt die Layouts-Seite von Mermaid sechs ELK-Varianten, die Sie als layout-Werte verwenden können: elk.stress, elk.force, elk.mrtree, elk.sporeOverlap, elk.box und elk.rectpacking.

---
config:
  layout: elk.mrtree
---
flowchart TD
  Root --> API
  Root --> Web
  API --> Workers

Laut den Release Notes zu 12.0.0 platzieren elk.box und elk.rectpacking zwar Knoten, führen aber kein Kanten-Routing durch. Ihre Kanten werden daher als gerade Linien von Mittelpunkt zu Mittelpunkt gezeichnet.

Ein einzelner Subgraph kann mit @{ algorithm: ... } einen eigenen Algorithmus wählen. Dieselben Release Notes nennen als zulässige Werte die sechs Varianten sowie elk.layered und elk.radial. Zu dieser Überschreibung halten sie außerdem zweierlei fest: Mermaid ignoriert nicht unterstützte Werte mit einer Warnung, und es verwendet stattdessen den geerbten Algorithmus, sobald Kanten die Grenze des Subgraphen überschreiten.

Warum funktioniert meine Layout-Korrektur nicht?

Die meisten fehlgeschlagenen Rücksetzversuche haben eine von fünf Ursachen. Prüfen Sie diese in folgender Reihenfolge:

1. Sie setzen weiterhin defaultRenderer. Die Syntaxseite zu Flowcharts weist darauf hin, dass dieser Schlüssel in v12 aus den Abschnitten für Flowchart, Class und State entfernt wurde. Verwenden Sie stattdessen layout.
2. Sie setzen nur layout: dagre. Das Theme redux-color und der Look neo sind weiterhin aktiv. Setzen Sie alle drei Schlüssel.
3. Front Matter überschreibt Ihr initialize(). Entfernen Sie layout aus dem Front Matter des betreffenden Diagramms.
4. Ein Layoutname ist falsch geschrieben oder nicht registriert. Laut den Release Notes fällt Mermaid in diesem Fall mit einer Warnung auf dagre zurück, statt einen Fehler zu werfen. Prüfen Sie die Konsole.
5. Sie verwenden den Tiny-Build. Siehe nächster Abschnitt.

Die Umstellung von defaultRenderer ist eine einzeilige Änderung:

// Before (removed in v12)
mermaid.initialize({ flowchart: { defaultRenderer: 'elk' } });

// After
mermaid.initialize({ layout: 'elk' });

Falls Ihre Dokumentationsplattform noch nicht auf v12 umgestellt hat, verhalten sich diese Schlüssel möglicherweise noch wie bisher. Prüfen Sie die Dokumentation der jeweiligen Plattform.

Warum fällt der Tiny-Build auf dagre zurück?

Der Tiny-Build von Mermaid enthält ELK nicht. Jedes Diagramm, das dort ELK anfordert, wird daher mit dagre gerendert. Für diesen Fall wird das Paket @mermaid-js/layout-elk weiterhin veröffentlicht. Folgen Sie den Registrierungsschritten im Abschnitt ELK and the tiny build der Nutzungsdokumentation. Im regulären Build funktionieren bestehende registerLayoutLoaders-Aufrufe weiterhin, sind aber nicht mehr erforderlich und können entfernt werden.

Fazit

Ein Diagramm, das sich nach dem Upgrade auf Mermaid 12 verändert hat, hat fast immer zwei Ursachen: die ELK-Layout-Engine sowie das neue Theme und den neuen Look. Entscheiden Sie, was Sie zurückhaben möchten. Wenn Sie nur die alten Formen wünschen, setzen Sie layout: dagre. Für die vollständige Darstellung wie vor Version 12 setzen Sie layout: dagre, theme: default und look: classic. Durchsuchen Sie anschließend Ihre Konfiguration nach verbliebenen defaultRenderer-Einstellungen und nach Front Matter, das Ihre seitenweite Einstellung überschreibt.

FAQs

Funktioniert das Diagramm-Schlüsselwort flowchart-elk in Mermaid 12 noch?

Ja. Laut den Release Notes zu Mermaid 12.0.0 funktioniert flowchart-elk weiterhin als explizites Diagramm-Schlüsselwort. Geändert hat sich die Option defaultRenderer. Mermaid ignoriert sie, statt sie abzulehnen. Eine Konfiguration, die sie noch setzt, wirft daher keinen Fehler, hat aber keine Wirkung. Ein Diagramm, das für sein ELK-Layout auf den flowchart-defaultRenderer-Wert 'elk' angewiesen war, sollte stattdessen layout: elk setzen.

Wird Mermaid 12 durch das mitgelieferte ELK beim Laden größer?

Nur der Single-File-Build wird spürbar größer. In den ESM-Builds ist ELK ein separater Chunk, der nur geladen wird, wenn ein Diagramm ihn verwendet. Laut den Release Notes zu 12.0.0 bindet der IIFE-Build mermaid.min.js ELK inline ein und wächst dadurch um etwa 500 kB (gzip-komprimiert). Der Tiny-Build lässt ELK weg, behält seine Größe bei und ordnet ELK-Anfragen mit dagre an.

Kann ich ELK-Optionen zur Feinabstimmung seitenweit statt im Front Matter jedes einzelnen Diagramms festlegen?

Ja. elk ist eine Top-Level-Eigenschaft im Mermaid-Konfigurationsschema. Sie können sie daher neben layout an mermaid.initialize() übergeben, zum Beispiel layout: 'elk' zusammen mit einem elk-Objekt, das mergeEdges: true und nodePlacementStrategy: 'NETWORK_SIMPLEX' enthält. Eine %%{init}%%-Direktive akzeptiert dasselbe elk-Objekt für ein einzelnes Diagramm. Front Matter in einem einzelnen Diagramm überschreibt die seitenweiten Werte weiterhin.