Mermaid sankey diagram examples

Mermaid sankey syntax: the CSV rules

Mermaid’s documentation describes the idea plainly: type the sankey-beta keyword, paste raw CSV underneath, get a diagram. The CSV follows RFC 4180 with two differences. It must have exactly three columns, read as source, target and value; and empty lines without commas are allowed for readability. A value with a comma inside goes in double quotes, and a literal double quote is written as two double quotes inside a quoted field.

Nodes are not declared anywhere. Every distinct name in the first two columns becomes a node, and a node that appears as a target in one row and a source in another connects the stages. Values can be decimals, as in Mermaid’s own energy example with figures such as 124.729. Mermaid still labels the diagram experimental and says the syntax may be extended, which is a reason to keep to these basics.

Do the flows have to balance?

No. Mermaid does not check that what flows into a node equals what flows out, and the diagram renders either way. Mermaid uses the d3-sankey layout, which sizes a node by the larger of its total inflow and its total outflow, so an unbalanced node simply shows a gap on its smaller side. That is sometimes what you want: the budget example above could leave the Budget node wider on the income side to show money left over.

Balanced data is easier to read, though, because every band that enters a node leaves it again. The funnel example is balanced by construction: each stage splits into the next stage and a drop-off node, and the two numbers add up to the stage total. When you build a sankey from real figures, add a node such as Other or Losses to absorb the difference rather than leaving readers to guess.

Which configuration options does a sankey diagram have?

All options sit under config: sankey in the YAML block at the top of the diagram. The first group has existed since the diagram arrived in Mermaid 10.3.0; the second group was added in 11.15.0.

Where does a sankey diagram render, and when should you use one?

The sankey diagram arrived in Mermaid 10.3.0 as sankey-beta; the -beta suffix was dropped from the documentation in 11.10.0 and both keywords are accepted in 11.16, so sankey-beta is the safer spelling for a document whose renderer you do not control. The node and label options need 11.15.0. GitHub renders mermaid blocks in issues, pull requests, discussions, wikis and Markdown files and suggests the info diagram to check its version; the Mermaid in Markdown page shows that check and the differences between GitHub, GitLab, Obsidian, Notion and VS Code. For readers elsewhere, paste the Markdown into the Docs MD editor and share the rendered page.

Use a sankey when the question is where quantities go: energy, money, traffic, people through a process. It is a poor fit for comparing independent totals, where a bar chart is clearer, and for shares of one whole, where a pie chart is enough. Keep to roughly a dozen nodes; the layout stays readable, and the CSV stays easy to update when the numbers change.

Is the Mermaid sankey keyword sankey or sankey-beta?

Both work in Mermaid 11.16. The diagram was introduced in 10.3.0 as sankey-beta; the suffix was dropped from the documentation in 11.10.0 and the parser has accepted either spelling since. Use sankey-beta when the document may be rendered by a platform on an older Mermaid, because versions between 10.3.0 and 11.9 only recognise that form.

Why does my Mermaid sankey diagram not render?

Almost always the CSV. Every data row needs exactly three comma-separated columns, so a name containing a comma must be in double quotes and a row must not end with a trailing comma. Node names must match exactly between rows, including case and spaces. Check the keyword is sankey-beta and that the config block, if present, is valid YAML. Finally confirm the platform runs Mermaid 10.3.0 or later with the info diagram.

How do I hide the numbers in a Mermaid sankey diagram?

Add a config block at the top of the diagram with sankey: showValues: false. The node names stay and the values disappear; the link widths still carry the proportions. Mermaid’s own documentation uses this setting in its main energy example because the raw figures clutter a diagram with many nodes.

Can I set the colour of a specific node?

Yes, from Mermaid 11.15.0: add a nodeColors map under config: sankey with the node name as the key and any CSS colour as the value, for example Losses: "#9ca3af". Nodes you do not list keep the default palette. For the links, set linkColor to source, target, gradient or a single hex colour; that option has existed since the diagram was added.

Can a Mermaid sankey diagram have a cycle?

No. A sankey shows flow in one direction, from sources on the left to sinks on the right, and the d3-sankey layout Mermaid uses rejects a loop with a circular link error, so a diagram with rows such as A,B,10, B,C,10 and C,A,5 fails to render. If a quantity genuinely returns to an earlier stage, such as recycled material, model the return as a separate node named for the return rather than linking back to the original node.