Mermaid mindmap examples

How does indentation work in a Mermaid mindmap?

A mindmap is a text outline. The first node after mindmap is the root and there can be only one: a second line at the root’s indentation makes Mermaid stop with the error “There can be only one root”. Every other line becomes a child of the nearest line above it that is indented less. The amount of indentation does not matter, only how it compares with the lines above, which is why the uneven example still produces a tidy map.

Because a parent is found by looking upwards, the order of lines matters as much as their indentation. To move a whole branch, move its lines together. To keep large maps readable in source, indent by a fixed step, such as two or four spaces per level, even though Mermaid would accept anything that is consistently deeper.

Turn a Markdown outline into a mindmap

Start from the list as it is written in the file. Put mindmap on the first line. Turn the one top-level bullet into the root, optionally in a shape such as root((Website redesign)); if the list has several top-level bullets, add a root above them, such as the document title, and indent every bullet one step. Then delete the bullet marker, - , * or 1. , from every line and keep the indentation exactly as it was. Mermaid reads a line indented further than the one above as its child, which is the same rule a Markdown list follows, so the hierarchy carries over without any edits. The example above was made this way from the outline in the table.

Two kinds of line need a hand. Text that contains parentheses or brackets, such as “Launch checklist (draft)”, has to go in quotes inside a shape with an ID in front, b1["Launch checklist (draft)"], or Mermaid reads the parentheses as a shape. Inline Markdown such as bold or a link has no meaning in a plain node: strip it, or wrap the label as a markdown string, a double quote and a backtick at each end, where **bold** and *italic* do work. Icons, ::icon(fa fa-book) on the line after a node, and classes, :::name, can be added afterwards; both only show where the renderer supplies the icon font or the CSS, so a converted map is usually left without them.

Both versions can live in the same Markdown file: the list stays readable text and the fenced mermaid block renders as the map on GitHub, GitLab, Obsidian and Docs MD. When the list changes, repeat the same steps; there is nothing else to keep in sync.

Which node shapes can a Mermaid mindmap use?

Mermaid’s documentation lists six shapes plus the default. The syntax follows flowcharts: an ID, then the text inside the shape’s delimiters. The ID is not shown; it only has to be there so Mermaid can tell the shape apart from the text.

How do icons and classes work in a mindmap?

An icon goes on the line after its node as ::icon(fa fa-book), with the icon font’s class names inside the parentheses; Mermaid’s documentation shows Font Awesome 5 and Material Design icons. The icon only appears if the site that renders the diagram has loaded that icon font, which the diagram author cannot do from inside the diagram. Mermaid marks the icon syntax as experimental and says it may change, which is the reason the mindmap diagram as a whole is still labelled experimental.

A class works the same way: :::urgent large on the line after a node attaches the CSS classes urgent and large to it. The CSS for those classes has to be supplied by the site, so on most platforms a class changes nothing. The examples on this page leave both out for that reason: they would render, but without visible icons or styles.

Why is my Mermaid mindmap not rendering as expected?

The most common surprise is brackets in plain text. A line such as Fix login (urgent) is read as a node with the ID “Fix login” and the rounded-square text “urgent”, so the first words disappear. Quote the text inside a shape instead: a1["Fix login (urgent)"], as in the retrospective example. The second is a second root, described above.

If the diagram does not render at all, check the renderer’s version. The mindmap has been part of Mermaid since 9.4.0; older versions needed a separate plugin. For markdown strings, the backtick must sit inside the double quotes at both ends of the label, and the label must be inside a shape such as square brackets. In Markdown files, the whole diagram goes in a fenced block tagged mermaid; see how to use Mermaid in Markdown.

Is the Mermaid mindmap still experimental?

Mermaid’s documentation still labels the mindmap experimental, but it also says the syntax is stable except for the icon integration. In practice, the outline syntax, shapes and markdown strings on this page are safe to use; the ::icon() syntax is the part that may change. The diagram has shipped with Mermaid since version 9.4.0, loaded on demand when a page first draws a mindmap.

Can a Mermaid mindmap have more than one root?

No. A mindmap has exactly one root, the first node after the mindmap keyword. If another line starts at the same indentation as the root, Mermaid stops with the error “There can be only one root”. To show two separate topics, make them children of a shared root, or draw two mindmaps one after the other in the same document.

How do you add a line break inside a mindmap node?

In a regular label, write <br/> where the line should break, as in “Ownership<br/>and borrowing” in the study map example. In a markdown string, the label wrapped in a double quote and a backtick at each end, press Enter inside the label and the new line carries into the node. Markdown strings also wrap long text automatically, so you rarely need manual breaks there.

Can you convert a Markdown list to a Mermaid mindmap?

Yes, by hand in three steps, because the two formats share one rule: indentation means hierarchy. Put mindmap on the first line, make the one top-level bullet the root (or add a root line above several), and delete the - marker from every line while keeping its indentation. Then quote any text with parentheses or brackets inside a shape, such as a1["Review (legal)"], and strip inline Markdown such as bold or links, or keep it in a markdown string. The outline example on this page shows the list and the resulting map side by side.

Does GitHub render Mermaid mindmaps?

GitHub renders fenced mermaid blocks in Markdown files, issues, pull requests, discussions and wikis using the Mermaid library, so a mindmap in standard syntax works there. GitHub controls which Mermaid version it runs, and icons need an icon font that GitHub decides whether to load. To see the version, GitHub’s documentation suggests rendering a one-word info diagram.

How do you change the colours of a Mermaid mindmap?

By default each top-level branch gets its own colour from the theme and its children share it. Choose another theme in a config block at the top of the diagram to change the palette. Per-node colours need classes, which only work where the site supplies the CSS. Mermaid’s current documentation adds a mindmap setting, colorBy: depth, that colours by level instead, but it needs Mermaid 12.2.0 or later.