# Mind maps

> Page: https://docs.plotwork.dev/mind-maps. Index of every page: https://docs.plotwork.dev/llms.txt

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](#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

```text
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.
```

```text
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.

**Diagram source**

```diagram
mindmap "Product launch" desc="What the team settles before the product ships: who it is for, what it is, where to say so, and what could go wrong."

root "Product launch" icon=lucide:rocket

topic "Audience" icon=lucide:users {
  topic "Maintainers"
  topic "Platform teams"
  topic "Technical writers"
  topic "Agency designers"
}

topic "Product" icon=lucide:package {
  topic "Text language"
  topic "Layout engine"
  topic "Light and dark themes"
  topic "MCP server and API"
}

topic "Channels" icon=lucide:megaphone {
  topic "Docs and guides"
  topic "Launch post"
  topic "Forums"
  topic "Newsletters"
}

topic "Plan" icon=lucide:calendar-clock {
  topic "Soft launch"
  topic "Public beta"
  topic "Week 12 review"
}

topic "Risks" icon=lucide:triangle-alert tone=red shape=hexagon {
  topic "Slow first render"
  topic "Unclear pricing"
  topic "Thin documentation"
}
```

*Picture: 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.*

**Text description**

**Central topic: Product launch**

**Branches:**

- Audience
  - Maintainers
  - Platform teams
  - Technical writers
  - Agency designers
- Product
  - Text language
  - Layout engine
  - Light and dark themes
  - MCP server and API
- Channels
  - Docs and guides
  - Launch post
  - Forums
  - Newsletters
- Plan
  - Soft launch
  - Public beta
  - Week 12 review
- Risks
  - Slow first render
  - Unclear pricing
  - Thin documentation

## 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.

```plotwork
mindmap "Product strategy" layout=radial

root "Product strategy" icon=lucide:target

topic "Growth" tone=blue icon=lucide:users {
  topic "Retention" {
    topic "Onboarding"
  }
}
```

### 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:

**Diagram source**

```diagram
mindmap "Release checklist" layout=down

root "Release" icon=lucide:rocket

topic "Before" {
  topic "Freeze the branch"
  topic "Run the full suite"
}

topic "During" {
  topic "Deploy the API"
  topic "Deploy the apps"
}

topic "After" {
  topic "Watch the dashboards"
  topic "Write the notes"
}
```

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

**Text description**

**Central topic: Release**

**Branches:**

- Before
  - Freeze the branch
  - Run the full suite
- During
  - Deploy the API
  - Deploy the apps
- After
  - Watch the dashboards
  - Write the notes

### 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:

**Diagram source**

```diagram
mindmap "Shapes, tones, and icons"

root "Every shape" shape=hexagon icon=lucide:star

topic "Pill, the default" icon=lucide:users {
  topic "A card" shape=card
  topic "A circle" shape=circle
  topic "A hexagon" shape=hexagon
}

topic "Tones" tone=violet shape=card {
  topic "Inherits violet"
  topic "Chooses green" tone=green
  topic "Chooses red" tone=red icon=status:error
}

topic "Icons" icon=lucide:package {
  topic "A bundled glyph" icon=lucide:database
  topic "A status icon" icon=status:success
  topic "A brand mark" icon=simple:github
  topic "A vendor's own" icon=aws:lambda
}

topic "A circle with an icon" shape=circle icon=lucide:target {
  topic "Short"
}
```

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

**Text description**

**Central topic: Every shape**

**Branches:**

- Pill, the default
  - A card
  - A circle
  - A hexagon
- Tones
  - Inherits violet
  - Chooses green
  - Chooses red
- Icons
  - A bundled glyph
  - A status icon
  - A brand mark
  - A vendor's own
- A circle with an icon
  - Short

## 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](https://docs.plotwork.dev/migrating-from-mermaid.md) covers the converter in full.

```mermaid-source
---
title: Product launch
---
mindmap
  root((Product launch))
    Audience
      Maintainers
      Platform teams
    Risks
      Slow first render
      ::icon(fa fa-bug)
    plan[Plan]:::warning
      Soft launch
      Public beta
    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`):

```plotwork
mindmap "Product launch"

root "Product launch"

topic "Audience" {
  topic "Maintainers"
  topic "Platform teams"
}

topic "Risks" {
  topic "Slow first render"
}

topic "Plan" shape=card tone=amber {
  topic "Soft launch"
  topic "Public beta"
}

topic "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.

## See also

| Doc | Why |
|---|---|
| [Writing diagrams](https://docs.plotwork.dev/writing-diagrams.md) | The flow, sequence and schema languages, and the rules every kind shares |
| [Examples to copy](https://docs.plotwork.dev/examples.md) | Finished diagrams with the prompt that gets an agent to write each one |
| [Migrating from Mermaid](https://docs.plotwork.dev/migrating-from-mermaid.md) | Convert existing Mermaid diagrams, and what is dropped |
| [Timelines](https://docs.plotwork.dev/timelines.md) | Events along a time axis, when the order matters more than the grouping |
| [User journeys](https://docs.plotwork.dev/user-journeys.md) | A person's path through a task, with how each step felt |
| [Git graphs](https://docs.plotwork.dev/git-graphs.md) | A repository history drawn as branches |
| [Gantt charts](https://docs.plotwork.dev/gantt-charts.md) | A plan drawn as tasks along a calendar |
| [Class diagrams](https://docs.plotwork.dev/class-diagrams.md) | Classes, their members, and how they relate |
| [State diagrams](https://docs.plotwork.dev/state-diagrams.md) | States and the transitions between them |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every kind, node type, option and diagnostic |
| [Diagram kinds](https://docs.plotwork.dev/reference/language/kinds.md) | The kinds Plotwork draws and the header of each |