Diagrams written as text: Mermaid and PlantUML

A diagram drawn with a graphics program has a problem that shows up over time: it is awkward to change. You have to find the source file, remember which program it was made with, move boxes and arrows by hand. So when the process changes, the diagram stays as it was and stops being true.

Diagrams written as text reverse the approach. You describe in a few lines what is connected to what, and a tool draws the diagram automatically. The source sits next to the document, is edited with any editor and is versioned with Git like everything else.

Mermaid

Mermaid is the most widespread tool for text diagrams inside Markdown. Many Git platforms, wikis and note apps render it directly: all it takes is a code block marked as mermaid.

Flowchart

```mermaid
flowchart TD
    A[Request received] --> B{Document complete?}
    B -- Yes --> C[Register]
    B -- No --> D[Ask for missing items]
    D --> A
    C --> E[Archive]
```

• flowchart TD sets a top-down diagram; LR lays it out from left to right.
• Square brackets create a box, braces a decision diamond, round brackets a rounded box.
• --> is an arrow; -- text --> adds a label.

Sequence diagram

This is useful for describing who talks to whom and in what order, for example in a login procedure:

```mermaid
sequenceDiagram
    User->>Portal: enters credentials
    Portal->>Server: verifies
    Server-->>Portal: requests second factor
    Portal-->>User: asks for the code
    User->>Portal: sends the code
    Portal-->>User: access granted
```

Solid arrows indicate a request, dashed ones a response.

Other types

Mermaid also supports Gantt charts for simple planning, state diagrams, entity-relationship diagrams for describing database tables, class diagrams and timelines.

PlantUML

PlantUML is older and more complete, especially for the UML diagrams used in software development. The text is enclosed between @startuml and @enduml:

@startuml
actor Operator
participant "Backup system" as B
database Archive

Operator -> B : starts copy
B -> Archive : writes data
Archive --> B : confirms
B --> Operator : final report
@enduml

It needs Java to run locally, and Graphviz as well for some diagram types. Many editors have extensions that show a preview as you type, and it can be integrated into documentation generators such as Sphinx or into company wiki software.

Which to choose

For documentation, procedures and READMEs, Mermaid is almost always enough. PlantUML is worth it when you need rigorous UML diagrams or special types.

Concrete advantages

• Quick changes: adding a step means writing one line, and the layout recalculates itself.
• Version history: Git shows exactly what changed in a diagram, which is impossible with an image.
• Consistency: all the diagrams in a project look the same.
• Review: reviewers read the diagram text like any other change.

Limits to be aware of

• Layout is automatic: you do not control to the millimetre where boxes end up. For highly polished schemes, such as a network map to hang on the wall, a graphics program such as draw.io remains better suited.
• Large diagrams get confusing: beyond twenty or thirty elements, it is better to split into several diagrams.
• Rendering depends on the platform: a Mermaid block that appears as a diagram in one repository may appear as text in another program. If the document has to be exported, it is best to generate an SVG or PNG image.
• Accessibility: the diagram should come with a short text description of what it shows.

In my work I use Mermaid to describe procedure flows and hand-offs between systems directly in the documentation: the diagram is updated in the same change that alters the process.

In short

• Text diagrams are written in a few lines and drawn automatically.
• Mermaid is built into many Markdown platforms and is the simplest to adopt.
• PlantUML offers more diagram types and more control, but requires Java.
• They are versioned and reviewed as text, and stay up to date more easily.
• For very polished or very large schemes, a graphics program or several small diagrams are preferable.