Other diagram kinds

Mind maps

A mind map draws one central idea and the branches that grow from it, with the idea in the middle and its branches on both sides, or as a tidy tree. Use it to plan, to sort a pile of thoughts, or to show what a topic is made of. It is for anyone who wants to see how ideas group, and for an agent that has been asked to organise them.

TL;DR

Question	Answer
What is it for?	A central idea and what grows from it: a plan, a brainstorm, a table of contents, a checklist by phase.
How do I start one?	Write `mindmap "Title"`, then one `root "Label"`, then `topic "Label"` lines. A topic with branches of its own ends its line with `{` and closes with `}`.
What does Mermaid convert?	`mindmap`. Indentation becomes nesting and shapes map to shapes. Icons and classes are reported. See From Mermaid.
How big can it be?	At most 300 topics and 10 levels below the root. Warnings start at 40 topics, 8 branches, 4 levels, and 9 topics under one topic.
How is it drawn?	Pills joined by tapering, curved ribbons. Each branch of the root takes its own tone, and every topic below it keeps that tone.
Which way does it read?	`layout=auto` draws the root in the middle when the map has two or more branches and fits a page column, and a tree growing right when it does not.

Ask your agent

Use Plotwork to draw a mind map of what a product launch has to settle. Put "Product launch" in the middle with four branches, Audience, Product, Channels and Plan, each with three or four topics. Add a fifth branch, Risks, as a red hexagon.

Use Plotwork to draw a mind map of our platform roadmap as a tree that reads left to right. Developer experience has local environments and faster CI, and faster CI has test sharding and a build cache. Reliability has multi-region failover and error budgets.

Example

A root, five branches, and the icons, tone and shape that set the last branch apart. The branches read clockwise from the top right.

Product launch: 24 topics, 5 branches, 2 levels. What the team settles before the product ships: who it is for, what it is, where to say so, and what could go wrong.

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. Indentation is for the reader and means nothing to the parser: nesting comes from the braces, so a line written at the wrong depth cannot silently move a topic.

Statement	Meaning	Example
`mindmap "Title" layout=<layout> desc="<text>"`	The header. Both options are optional, and so is the title: with no title, the text of the root names the picture.	`mindmap "Product strategy" layout=radial`
`desc "<text>"`	The plain-language description, as a statement. The same as `desc=` on the header.	`desc "Three bets for the year."`
`root "<label>" icon=<set:name> tone=<tone> shape=<shape>`	The central idea. Write it once, before every topic.	`root "Product strategy" icon=lucide:target`
`topic "<label>" icon=<set:name> tone=<tone> shape=<shape>`	A branch of the root at the left margin, or of the topic whose block it sits in.	`topic "Growth" tone=blue icon=lucide:users`
`topic "<label>" {`	A topic with branches of its own. End the line with `{`, write the branches on the lines after, and close with `}`.	`topic "Retention" {`
`}`	Closes the nearest block that is still open, on a line of its own.	`}`

The branches of the root are the topics at the left margin, so the root needs no block of its own. A topic has no id, because a mind map has no cross references. A habit from flow diagrams such as topic seo "SEO" is refused with E100, and the hint gives the form to write.

1mindmap "Product strategy" layout=radial2
3root "Product strategy" icon=lucide:target4
5topic "Growth" tone=blue icon=lucide:users {6  topic "Retention" {7    topic "Onboarding"8  }9}

Options

Option	On	Values	Default
`layout=`	header	`auto`, `radial`, `right`, `down`	`auto`
`desc=`	header	quoted text	none
`icon=`	root, topic	any bundled icon, such as `lucide:users`, or `none`	none
`tone=`	root, topic	`neutral`, `blue`, `violet`, `aqua`, `orange`, `green`, `amber`, `red`	the tone of the branch, and `neutral` for the root
`shape=`	root, topic	`pill`, `card`, `circle`, `hexagon`	`circle` for the root, `pill` for every topic

Layouts

Value	What it draws	Best for
`auto`	`radial` when the root has two or more branches and the picture is at most 1100px wide, and `right` when it does not.	Most maps.
`radial`	The root in the middle. The first branches go down the right side, and the rest come up the left side from the bottom, so the branches read clockwise from the top right. The split makes the two sides the same height. Each side is a tidy tree growing away from the root.	Two levels below the root, or three with short labels.
`right`	A tidy tree. The root is at the left and every level is a column to its right.	Deep maps and long labels, which keep the narrowest picture.
`down`	A tidy tree. The root is at the top and every level is a row below it.	A small map read as a hierarchy. It is the widest of the three for a bushy map.

A checklist by phase reads well as a tree growing down:

Release checklist: 10 topics, 3 branches, 2 levels.

Shapes

Value	What it draws
`pill`	A capsule. A label of several lines turns it into a rounded card, so the corners never cut the text.
`card`	A rounded rectangle with the corners of a flow node.
`circle`	An ellipse. A short label wraps into a round shape. With an icon, the icon sits above the text.
`hexagon`	A hexagon with its points at the sides, for a topic that deserves emphasis.

Colour

A branch of the root takes the next tone of the rotation blue, orange, aqua, violet, amber, green, red, which starts again after the seventh. Every topic below it keeps that tone, so the colour says which branch a topic belongs to. A tone= on a topic changes it and everything below it. The root is the ink colour unless it has a tone. Nobody writes a colour value: the theme owns every colour, in light and in dark.

The branch of the root is a tinted pill with bold text, a topic below it sits on the surface with a quieter outline, and from the fourth level down the text takes the secondary ink.

Shapes, tones and icons together:

Shapes, tones, and icons: 16 topics, 4 branches, 2 levels.

Limits and warnings

Limit	Value	What happens past it
Topics, the root included	300	`E140` before any layout, with the advice to split the map by branch.
Levels below the root	10	`E422`, once, at the first topic past the limit.
Topics before the density warning	40	`W200`.
Branches of the root before the warning	8	`W362`. The seven branch tones repeat after the seventh.
Levels before the warning	4	`W361`.
Topics under one topic before the warning	9	`W363`, at that topic.
Text width	188px preferred, 300px hard, 3 lines	Text wraps at the preferred width, and a long word widens the topic up to the hard width. Only past that is text cut with an ellipsis, with warning `W203`.

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

Code	When it fires	Fix
`E420`	A topic comes before the root, the root comes after a topic, or there is no root.	Write one `root` first, then the topics.
`E421`	A second `root`. It is read as a topic, so nothing else is reported for it.	Keep one `root`. Make the other a `topic`, or split the map.
`E422`	More than 10 levels below the root.	Flatten the map or split it by branch.
`E423`	A label with no text.	Give the root or the topic a label.
`E424`	The root has a block. Its branches are the topics at the left margin. It is read as a block, so nothing else is reported.	Remove the braces after the root and move the topics to the left margin.
`E140`	More than 300 topics.	Split the map by branch.
`E100`, `E101`, `E110`, `E121`, `E122`, `E133`, `E134`, `E135`, `E136`	The shared codes: syntax (a topic with an id is one), an unterminated string, an unknown statement, an unknown tone or icon, an unclosed block or a stray `}`, an unknown option, and a bad value such as a layout or a shape.	Read the hint, which names the line to write.
`W360`	A root with nothing under it.	Add topics, or keep the map as a placeholder.
`W361`	More than 4 levels.	Split the map, or shorten the chain of branches.
`W362`	More than 8 branches of the root.	Group related branches under one, or split the map.
`W363`	More than 9 topics under one topic.	Group them under two or three topics.
`W364`	A label repeated under one parent, in any case.	Rename one, or merge them.
`W200`	More than 40 topics.	Split the map by branch.
`W202`	The picture is wider than a Markdown column and its text would shrink.	Use `layout=right`, shorten labels, or split the map.
`W203`	Text was cut with an ellipsis.	Shorten the label.

From Mermaid

Mermaid mindmap converts to a mind map. The first node is the root, and a node is a child of the nearest node above it that is indented less, as Mermaid reads it. Indentation may be spaces or tabs, in any steps. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1---2title: Product launch3---4mindmap5  root((Product launch))6    Audience7      Maintainers8      Platform teams9    Risks10      Slow first render11      ::icon(fa fa-bug)12    plan[Plan]:::warning13      Soft launch14      Public beta15    Channels))Launch post((

The converter reports the dropped icon (M281), the tone it took from the class (M207), and the bang shape it replaced with a hexagon (M280):

1mindmap "Product launch"2
3root "Product launch"4
5topic "Audience" {6  topic "Maintainers"7  topic "Platform teams"8}9
10topic "Risks" {11  topic "Slow first render"12}13
14topic "Plan" shape=card tone=amber {15  topic "Soft launch"16  topic "Public beta"17}18
19topic "Launch post" shape=hexagon

Mermaid	Plotwork	Report
`root((text))` and `id((text))`	`shape=circle`, the default for the root, so none is written there	none
`id[text]` and `id(text)`	`shape=card`	none
`id{{text}}`	`shape=hexagon`	none
`id))text((` (a bang)	`shape=hexagon`	`M280`, with the hint to remove it
`id)text(` (a cloud)	a pill, the default	`M280`, with the hint to give it a tone
Plain text	a topic, drawn as a pill. A plain root is the default root.	none
Text before a bracket, as in `Pen (analog)`	Dropped. Mermaid keeps it as the id and never draws it.	`M282` when it has white space or reads as text
`::icon(fa fa-book)`	Dropped, because Plotwork icons are a closed set.	`M281` at the icon line, with the closest bundled icon in the hint
`:::error` and the like	`tone=red` for a class that names a tone (`error`, `warning`, `success`, and the rest of the shared table)	`M207`
Any other class	Dropped.	`M200`
`<br/>` and other HTML, Markdown marks	Removed. A line break becomes a space.	`M205`
A Font Awesome token in the text	Removed.	`M215`, with the closest bundled icon
An empty label	The id, or the node is dropped when it has none.	`M216`
Front matter `title:` and `accTitle:`	The title.	none
`accDescr:`	`desc=`	none
Front matter `config:` and `%%{init}%%`	Dropped.	`M200`
`%%` comments	Dropped.	none
A second root	Nothing is converted.	`M180`
More than 300 nodes, or more than 10 levels	Nothing is converted.	`M102`
A line that cannot be read	Nothing is converted, or the line is skipped when the conversion is lenient.	`M110`, or `M218`

The converter sets a tone only from a class that names one, so every other branch takes the next tone of the rotation. Choose a tone= on a branch where its colour should mean something, and an icon= on a topic where a glyph helps.

Doc	Why
Writing diagrams	The flow, sequence and schema languages, and the rules every kind shares
Examples to copy	Finished diagrams with the prompt that gets an agent to write each one
Migrating from Mermaid	Convert existing Mermaid diagrams, and what is dropped
Timelines	Events along a time axis, when the order matters more than the grouping
User journeys	A person's path through a task, with how each step felt
Git graphs	A repository history drawn as branches
Gantt charts	A plan drawn as tasks along a calendar
Class diagrams	Classes, their members, and how they relate
State diagrams	States and the transitions between them
Language reference	Every kind, node type, option and diagnostic
Diagram kinds	The kinds Plotwork draws and the header of each