Mermaid flowchart layout

Mermaid is not a diagram editor – it is in fact something more interesting. Mermaid is a diagram description language paired with a rendering engine. The language defines syntax rules for describing diagrams. The rendering engine turns a diagram description into a visual image.

What's interesting about this is that the diagram is produced automatically from the given Mermaid text. There's no mouse work involved – no pointing and clicking or moving diagram parts around in a designer application – immediate output is a significant benefit of the Mermaid system.

The downside is that you can't easily modify the diagram that you're given. Layout is primarily determined by your choice of rendering engine, and presentational style is also a result of what the renderer supports.

Modifying Mermaid layout

Before concluding that Mermaid can't give you the layout you're aiming for, you should be aware of the special syntax options that exist to give hints to the stock renderer about what you want to see. To adjust where nodes are positioned there are six syntax tweaks to consider. None of these place a node, they are requests that the renderer may override to meet other objectives.

TweakDescriptionCaveatsAvailability
Extra dashes
--->		A request for the edge to span at least two ranks. The dotted form needs extra dots: -..->.A length hint, not a command to put two nodes on the same rank.Stock Mermaid
- dagre only
- not implemented in ELK.
Invisible links
A ~~~ B		Invisible links can affect placement without drawing a visible relationship between the nodes.Unpredictable effect – layout can change in large, unexpected ways when links change, so trial-and-error is needed to find the best compromise.Stock Mermaid
both dagre and ELK.
SubgraphEnclosed nodes stay in a confined, separated area of the diagram, which can help the layout.Adds a spurious box around the grouped nodes – hide it with targeted styling. Not a syntax refinement – a hack used for its side-effect. Lines between nodes external and internal to the subgraph may route differently when the subgraph is present.Stock Mermaid
both dagre and ELK.
Subgraph directionA direction (e.g. TB, LR) can be assigned to a subgraph to request a layout direction for its nodes, separately to the layout direction for the flowchart as a whole.Ignored by the renderer when nodes inside the subgraph are linked to nodes outside.Stock Mermaid
both dagre and ELK.
Subgraph declaration orderThe order in which sibling subgraphs are declared in the Mermaid text changes the order in which they're rendered inside the parent element. The ordering is the reverse of the declaration order.NoneStock Mermaid
both dagre and ELK.
Node declaration orderThe order in which nodes are first defined in the Mermaid text has a bearing on the order in which they are included in the rendered graph. Within a ranking (level) the node order initially follows declaration order but is then often overridden during later processing when necessary to try to prevent lines from crossing.Some influence in node placement is possible but is subservient to the line crossing objective.Stock Mermaid
both dagre and ELK.

The & syntax looks as if it might group nodes or put them on the same rank. It does not. It is only a shorter way to write several links: A --> B & C is the exact same graph as A --> B and A --> C.

Problems with Layout adjustments

Even when you're able to obtain an acceptable layout by adjusting or hacking the source text, this practice isn't a good solution to the layout problem:

  • The detailed syntax rules are relatively obscure and hard to remember, so frequent references to the documentation pages is needed.
  • It's not possible to guess in advance what text changes will result in the best layout, so a trial-and-error approach is needed, which is time-consuming and frustrating.
  • Different viewing surfaces for Mermaid diagrams use different rendering libraries, or different versions of them, so the final appearance of your diagram can change, depending on where you look at it.

In any case, it's often found that no syntax tweaks can achieve the flowchart layout that you're aiming for. Many of the problems observed with Mermaid layouts are deep-seated. Your options for addressing layout are:

  • switching the Mermaid rendering engine (see below);
  • redrawing the graph in a drawing editing tool – but then the portability is lost and your diagram no longer stays together with the code it documents.

Change the rendering engine

Dagre and ELK

The stock Mermaid library has built-in support for two rendering engines: the default, dagre and the alternative, ELK. ELK often improves on the dagre output, so can be worth trying – just add this in the frontmatter section of the Mermaid text:

---
config:
  flowchart:
    defaultRenderer: "elk"
---

Although ELK often gives an improved layout, you should be aware that the ELK engine is not always present in the surfaces where you look at your diagram. Popular viewing surfaces that don't include ELK support include GitHub, GitLab, Notion, Obsidian, Typora and VS Code.

Line9

Line9 is a Mermaid rendering engine designed specifically for making flowchart diagrams immediately usable, readable and presentable. It does so by using a very different layout algorithm and rendering choices.

As with all other Mermaid renderers, Line9 can't provide specific node placement or rank. Unlike stock Mermaid renderers, Line9 ignores layout hints such as extra dashes for longer lines, or directions in subgraphs. Instead its layout logic often (not always) gives a better flowchart layout automatically. You can easily compare the layout from Line9 against the stock Mermaid layout from the /diagram page, or read Line9 vs mermaid.live for the full account.

Line9 renders are watermarked when free and rendering, sharing and export are always free. The CLI is free for personal use. Line9 is closed source.

Try it with your Mermaid text to see the difference that it makes.

AI Generated Diagrams

Increasingly AI is used to write all Mermaid text and it's expert at capturing logic and presenting diagrams quickly. However, although they're highly accomplished in writing content, they're not well suited to visualizing the layout. Therefore they don't know which syntax hints to include to finesse the result. The fastest way to a good layout from AI is with Line9's CLI so you get the readability without the edits.

Specific layout problems

1 published

Diagram examples are listed at Mermaid examples.