Migrating from Mermaid

TL;DR

Why migrate

GitHub already draws Mermaid fences in the page, so Mermaid works with no setup. Plotwork gives you these in return for the move:

When not to migrate

Keep the Mermaid fence when the diagram is one of the kinds in the next table. GitHub keeps drawing it. A fence that cannot be converted is left exactly as it was, so a document can hold both kinds.

Mermaid kinds Plotwork does not draw

These kinds used to be on this list and now convert to their own kinds: C4 diagrams, class diagrams, Gantt charts, git graphs, mind maps, pie charts, quadrant charts, Sankey diagrams, timelines, tree views, treemaps, user journeys, and XY charts. A state diagram is now a state diagram and no longer a flow diagram. Other Mermaid kinds that convert says where each one is explained.

The migration recipe for an agent

Follow these steps in order. Each one is a tool call or a decision.

1. Convert. For one diagram, call convert_mermaid with the text inside the fence. For a document, call sync_markdown with convertMermaid: true.
2. Read every diagnostic. They are data: code, severity, line, column, message, and a hint that says what to do. Lines and columns point into the Mermaid you sent. A code that starts with M1 is an error and nothing was converted. A code that starts with M2 is a warning and the conversion went on.
3. Resolve each one with the guidance in what does not carry over and the diagnostic codes. Most need no action. Some need a choice, such as which node an edge into a subgraph should reach.
4. Make it meaningful. The converter chooses a node type only when the shape or a short label says what the node is. Every other node is a plain step. Choose a better type for each (see how a node type is chosen), give the diagram a title, and name the groups. Take the icon suggestions in validation.warnings: each says which icon= to write. Find others with search_icons or map_icons.
5. Validate. Call draw_diagram on the edited Plotwork source. It returns every error and warning, and draws nothing until the source is valid.
6. Render. Call draw_diagram again for the pictures, or put the source in a diagram fence and call sync_markdown. See Diagrams in Markdown and on GitHub.

Worked example: one call and its result

The call:

1{2  "tool": "convert_mermaid",3  "arguments": {4    "source": "flowchart TD\n  user[User] --> db[(Orders DB)]\n  classDef error fill:#f66\n  class db error",5    "render": false6  }7}

The source argument, written out one line at a time:

1flowchart TD2  user[User] --> db[(Orders DB)]3  classDef error fill:#f664  class db error

The result, shortened to the fields an agent reads first:

1{2  "ok": true,3  "kind": "flow",4  "mermaidType": "flowchart",5  "source": "flow direction=down\n\nnode user person \"User\"\nnode db database \"Orders DB\" tone=red\n\nuser -> db",6  "diagnostics": [7    {8      "code": "M214",9      "severity": "warning",10      "line": 1,11      "message": "The diagram has no title.",12      "hint": "Add a title to the header line of the Plotwork source, or a title: line in the Mermaid front matter."13    },14    {15      "code": "M204",16      "severity": "warning",17      "line": 3,18      "message": "The fill #f66 of the class \"error\" became the tone red.",19      "hint": "Check that the tone says what it means. The theme draws it in light and dark."20    }21  ],22  "stats": {23    "nodes": 2,24    "edges": 1,25    "groups": 0,26    "dropped": 0,27    "renamed": 028  },29  "validation": {30    "valid": true,31    "errors": [],32    "warnings": []33  },34  "outline": [35    "Nodes:",36    "- User, person",37    "- Orders DB, database",38    "Connections:",39    "- User to Orders DB"40  ],41  "next": "Read the 2 diagnostics (they point into the Mermaid) and fix what the hints say. Then choose a meaningful type for every node left as step, add a title, and take the icon suggestions in validation.warnings. Call draw_diagram on the edited source to check and draw it, or sync_markdown to place it in a document."42}

The source of the result, written out one line at a time:

1flow direction=down2
3node user person "User"4node db database "Orders DB" tone=red5
6user -> db

The field ok is true only when source passes the Plotwork parser. When it is false, source is empty and diagnostics holds the reason, so the converter never returns source that would fail validation.

Worked example: a whole document

Ask the agent: "Replace the Mermaid diagrams in README.md." The tool sequence is:

The result, shortened:

1{2  "mode": "sync",3  "markdown": "<the whole document, rewritten>",4  "changed": true,5  "files": [6    {7      "path": "assets/diagrams/readme-sign-in-flow.svg",8      "content": "<svg text>",9      "encoding": "utf8"10    },11    {12      "path": "assets/diagrams/readme-sign-in-flow.dark.svg",13      "content": "<svg text>",14      "encoding": "utf8"15    }16  ],17  "report": [18    {19      "id": "readme-sign-in-flow",20      "source": "mermaid",21      "kind": "flow",22      "line": 12,23      "status": "converted",24      "diagnostics": [],25      "message": null26    }27  ],28  "summary": {29    "diagrams": 1,30    "synced": 0,31    "converted": 1,32    "unchanged": 0,33    "skipped": 0,34    "failed": 0,35    "files": 236  },37  "caps": {38    "hit": false,39    "messages": []40  }41}

A call handles up to 30 diagrams and a document of up to 10 million characters. If a document has more, caps says which fences were skipped; send them in a second call. Nothing is cut silently.

Concept mapping

These tables are the converter's own data, so they cannot drift from what it does.

Flowchart shapes

Shapes written in the newer A@{ shape: name, label: "text" } form map the same way:

Edges

Edge text written as -->|text| or -- text --> becomes the edge label. A chain such as A --> B --> C and a fan such as A & B --> C & D become one edge for each pair. An edge animation, e1@{ animate: true }, is kept as animate=on on the line. The edge id and the speed are dropped and reported, and a link with no arrowhead stays still, because dashes travel toward an arrowhead.

Subgraphs

Sequence diagrams

Arrows:

Blocks:

Everything else:

Entity relationship diagrams

A Mermaid relationship names two entities and no columns. A Plotwork relation joins one column to another, so the converter finds the key columns, and adds a column when it cannot. Each added column is reported.

Whole relationships:

Lines and keys:

State diagrams

A state diagram becomes a Plotwork state diagram, which has its own kind: states are rounded cards, transitions are labelled lines, composite states are frames, and the start and end markers, choices, forks, joins and notes are drawn as such. Older versions of the converter turned a state diagram into a flow diagram of groups and terminal nodes, so a state diagram that was converted earlier reads differently when it is converted again. See State diagrams.

Other Mermaid kinds that convert

More Mermaid kinds convert into a Plotwork kind of their own. Each has a guide that shows what is kept and what is dropped. The codes in the last column are the ones that only that kind raises, and the diagnostic codes table explains every code.

Three kinds have no Mermaid type to read: Layered architecture, Matrices, and Swimlane diagrams. Each guide says how to move a Mermaid diagram or a Markdown table to it by hand.

How a node type is chosen

The converter is conservative. It picks a type in this order and stops at the first that applies:

1. The construct itself decides, as for a flowchart rhombus (a decision) or a stadium (a terminal).
2. A class name that carries meaning, such as database, queue, external, or error. The converter reports that it used the class.
3. The shape: a cylinder is a database, a rhombus is a decision, a stadium or a circle is a terminal, a cloud is external. A label keyword may refine a cylinder to a cache, a queue, or storage.
4. A keyword in a short label of at most three words, and only when exactly one type matches. "Orders DB" is a database; "Redis queue" matches two types and stays neutral; a sentence is never read.
5. Otherwise the neutral step, which the converter lists in one warning so you choose a better one.

It writes an icon only when the label names a brand. "PostgreSQL", "Redis cache", or a second line such as "Stripe API" gets that brand's mark (icon=simple:postgresql). A decision, a start or end, and a plain step never get one, and a name that is only a word for a kind of thing ("Message Queue") keeps the icon of its type. The Plotwork validator suggests the other icons from the labels, and those suggestions come back in validation.warnings.

An HTTP status code at the start of a label sets a tone when the node has none: 200 and the other 2xx codes are green, and 4xx and 5xx codes are red. "Return 429 Too Many Requests" is red. A 3xx code gets no tone, because a redirect is neither good nor bad.

The words it looks for:

Class names that give a type or a tone:

Fills become tones

A style line, a classDef line, and a class or :::name that points at one can set a fill. The converter reads the fill and keeps it as the tone of the node (or the group) when the colour is clear: it works out the hue of the colour and takes the tone whose band holds it. Each one is reported with M204, the first few on their own and the rest in one summary, so a diagram painted by an agent is not buried in warnings. A tone is a meaning, and the theme draws it in light and dark.

These fills become no tone, and are reported as dropped styling with M200 along with the strokes, text colours, and widths:

A fill set on the node itself wins over a tone a class name such as error suggests.

Edge labels that get a status icon

An edge label that states an outcome gets a status icon, written as icon=status:name on the line. The icon brings its own colour, so a branch such as "Rate limited" says what happened without a colour code to learn. A label matches only when all of it is one of the phrases below, in any case and with its punctuation ignored, so "Sends the order" and "Webhook" are never given an outcome they do not state. The labels yes, no, true, and false get their tick and cross from the language itself, so the converter writes nothing for them.

What does not carry over and why

Plotwork owns colour, spacing, and layout, so a diagram cannot set them. The rule for every row is the same: choose a node type or a tone for meaning, and let the theme choose the colour.

Other text is cleaned and the change is reported: HTML tags and Markdown marks are removed, <br/> and \n become a line break (a second line of a node label becomes its sub= text), entities such as #quot; and & are decoded, and Font Awesome tokens such as fa:fa-database are removed with the closest bundled icon named in the hint. Quotes and backslashes are escaped so every label keeps its exact text.

Ids that are not valid Plotwork ids (spaces, dots, accents, a leading digit) are renamed the same way every time, and each rename is reported. The label keeps the original text.

Diagnostic codes

Diagnostics from the converter point into the Mermaid. The Plotwork validator's own warnings, such as an icon suggestion, point into the converted source, and they come back separately in validation.

Before and after

Each example shows the Mermaid source, the picture Mermaid draws from it, the Plotwork the converter produced, the picture Plotwork draws from that, and a table of what differs, with nothing edited by hand. After the conversion, an agent would still read the diagnostics, choose types for the nodes left as step, and take the icon suggestions.

The Mermaid pictures were drawn with Mermaid 12.1.0, in its default and dark themes, with Arial text. They are fixed pictures, drawn once from the source above them. They are not drawn by this page.

Some differences hold for every diagram:

A flowchart with a subgraph and a decision

Mermaid:

1---2title: Sign-in flow3---4flowchart TD5  user[User] --> gw[API gateway]6  gw --> auth{Credentials valid?}7  auth -->|yes| session[Create session]8  auth -->|no| denied([Access denied])9  subgraph store [Data]10    db[(Users DB)]11    audit[Audit log]12  end13  auth -.-> db14  session --> audit15  classDef database fill:#9cf16  class audit database

Mermaid draws it like this:

The converter reports the database type it took from the class of that name for the audit log, the class's blue fill kept as the tone blue, and the one node left as a plain step. The Plotwork:

PictureSourceOutline

What differs between the two pictures:

A sequence diagram with an alt block

Mermaid:

1---2title: Token refresh3---4sequenceDiagram5  autonumber6  actor U as User7  participant A as App8  participant I as Identity provider9  U->>A: Open the app10  A->>+I: Refresh token11  alt token valid12    I-->>-A: New access token13  else token revoked14    I-->>A: 401 sign in again15    A->>U: Ask to sign in16  end17  Note over A,I: Tokens last 15 minutes

Mermaid draws it like this:

The converter turns autonumber into numbered=on on the header, reports the dropped activation marks, and reports the participant App left as a plain step. The actor became a person, and the name Identity provider became an identity. The Plotwork:

PictureSourceOutline

What differs between the two pictures:

An entity relationship diagram

Mermaid:

1---2title: Orders3---4erDiagram5  CUSTOMER ||--o{ ORDER : places6  ORDER ||--|{ LINE_ITEM : contains7  CUSTOMER {8    int id PK9    string email UK10    string name11  }12  ORDER {13    int id PK14    int customer_id FK15    date placed_at16  }17  LINE_ITEM {18    int order_id FK19    string sku20    int quantity21  }

Mermaid draws it like this:

The many side of each relationship holds the foreign key, and the converter matched each one to a column that was already declared as FK, so it added none. It reports that the "one or more" minimum on contains is not drawn. The Plotwork:

PictureSourceOutline

What differs between the two pictures:

Converting a documentation folder safely

Go one file at a time, and read before you write. Ask your agent to run the steps, or make the calls yourself.

To convert a whole folder, ask the agent to call sync_markdown on each file. Keep the dry run first for every file.

For a single diagram, call convert_mermaid with the Mermaid text. It returns the Plotwork source and the diagnostics as data, and you decide where to save the source.

FAQ

See also