mermaid

The mermaid library is part of DiagrammeR. With it, you can describe graphs and sequence diagrams.

DiagrammeR Implementation

For mermaid diagrams, DiagrammeR uses the processing function called mermaid. What you pass into mermaid is a valid graph or sequence diagram specification. The specification can either be delivered to mermaid in the form of a string, a reference to a mermaid file (with a .mmd file extension), or as a text connection.

All of the code examples provided in later sections call the mermaid function in an R script and pass in a specification as a string. It is important to consider that strings in R cannot contain any unescaped double-quote characters. However, the mermaid function allows for single-quote characters in their place. As a further convenience, when a mermaid graph description is supplied as a file (e.g., 'mermaid-graph.mmd') or as a text connection, either format for quotes will be accepted.

In very recent builds of RStudio, the use of an external text file with the .mmd file extension can provide the advantage of syntax coloring and previewing in the RStudio Viewer pane after saving (if 'Preview on Save' is selected), or, by pressing the 'Preview' button on the Source pane.

Defining a mermaid Graph

The mermaid graph specification begins with a declaration of graph followed by the graph direction. The directions can be

  • LR left to right
  • RL right to left
  • TB top to bottom
  • BT bottom to top
  • TD top down (same as TB)

Nodes can be given arbitrary ID values and those IDs are displayed as text within their respective boxes. Connections between nodes are denoted by:

  • --> arrow connection
  • --- line connection

Simply joining up a series of nodes in a left-to-right graph can be done in a few lines:

mermaid("
graph LR
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F
")

The same result can be achieved in a more succinct manner with this R statement (using semicolons between statements in the mermaid diagram spec):

mermaid("graph LR; A-->B; A-->C; C-->E; B-->D; C-->D; D-->F; E-->F")

Alternatively, here is the result of using the statement graph TB in place of graph LR:

mermaid("
graph TB
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F
")

Keep in mind that external .mmd files can also be called by the mermaid function. The file graph.mmd can contain the text of the diagram specification as follows:

graph LR
  A-->B
  A-->C
  C-->E
  B-->D
  C-->D
  D-->F
  E-->F

and be rendered through:

mermaid("graph.mmd")

Node Shape and Text

When assigning nodes, the default behavior is to assign the node IDs as text within the node objects. The addition of text inside node objects occurs through simultaneous assignment of both the node shape and the node label. The syntax for assigning text to a label is

[ID][opening brace][label][closing brace]

There the different types of patterns of opening and closing braces enclosing the label that change the shape of the node. Using [ and ] yields text in a rectangular node

mermaid("
graph LR
  A[node text]
")

Text placed in a node shaped as a rounded rectangle is done using ( and )

mermaid("
graph LR
  A(node text)
")

A circular node with text can be created by encapsulating the text with (( and ))

mermaid("
graph LR
  A((node text))
")

A rhombus node is made with { and }

mermaid("
graph LR
  A{node text}
")

Finally, there is a special type of shape which is asymmetric and resembles a flag. Only one representation is possible at this time, which is constructed with > and ]

mermaid("
graph LR
  A>node text]
")

Combining these node shapes together in a single graph, the following may be obtained

mermaid("
graph LR
A(Rounded)-->B[Rectangular]
B-->C{A Rhombus}
C-->D[Rectangle One]
C-->E[Rectangle Two]
")

Sequence Diagrams

The mermaid.js library also supports sequence diagrams.

Defining a Sequence Diagram

The "How to Draw Sequence Diagrams" report by Poranen, Makinen, and Nummenmaa offers a good introduction to sequence diagrams. Let's replicate the ticket-buying example from Figure 1 of this report and add in some conditionals.

mermaid("
sequenceDiagram
  customer->>ticket seller: ask ticket
  ticket seller->>database: seats
  alt tickets available
    database->>ticket seller: ok
    ticket seller->>customer: confirm
    customer->>ticket seller: ok
    ticket seller->>database: book a seat
    ticket seller->>printer: print ticket
  else sold out
    database->>ticket seller: none left
    ticket seller->>customer: sorry
  end
")