Diagraming With Mermaid

comments edit

Mermaid is a tool that will generate diagrams from a basic definition language.

The mermaid website has full description of the language and features: https://knsv.github.io/mermaid/#syntax

A Simple Example

The following snippet will create a simple sequence diagram.

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!

The above diagram renders as:

sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great!

Tools

There are various tools that you can use to edit and save diagrams as images

Mermaid CLI

Pros and Cons

Pros

  • Export diagram as an image

Cons

  • No live updating diagram as you type
  • Syntax requires a non-standard but simple header of ```mermaid

Setup and Use

  1. Install node.js
  2. Install the mermaid npm package 
     npm install -g mermaid
  3. Install the phantomjs npm package 
     npm install -g phantomjs
  4. Save the following diagram definition to a file sequence.mmd 
     sequenceDiagram
     Alice->>John: Hello John, how are you?
     John-->>Alice: Great!
  5. Run mermaid command 
     mermaid sequence.mmd
  6. Open the image found at sequence.mmd.png

sequence.mmd.png

Visual Studio Code

Pros and Cons

Pros

  • Live updating diagram as you type

Cons

  • No easy way to export diagram as an image
  • Syntax requires a non-standard but simple header of ```mermaid
  • Supports the activate/deactivate keywords that are unsupported by other processors

Setup and Use

  1. Download and install Visual Studio Code (this is entirely different than the “normal” Visual Studio you use to write C# code)
  2. In Visual Studio Code download and install the Mermaid Preview extension
  3. Restart Visual Studio Code when prompted
  4. Create a new markdown file named sequence.md
  5. Paste in the following diagram definition (including the lines that start with three backticks) 
         ```mermaid
     sequenceDiagram
         Alice->>John: Hello John, how are you?
         John-->>Alice: Great!
     ```
  6. Press <control-p> to bring up the Visual Studio Code command window
  7. Type in > Preview Mermaid Diagram
    • Include the > character
    • You only need to type enough of the command that it shows up in the menu
    • You can type in various short cuts that will also bring up the command quickly
      • > Mermaid
      • > PMD (just the initials)
  8. Click on any of the text in the left pane that is part of the diagram definition

Sample Diagram in Visual Studio

Atom

Pros and Cons

Pros

  • Live updating diagram as you type
  • Export diagram to PNG or SVG

Cons

  • Exported diagram has a blank background (you need to manually open the file and add a non-transparent background to be able to view the image)

Setup and Use

  1. Install Atom editor
  2. Install Mermaid Preview extension
  3. Create a new markdown file named sequence.mmd
  4. Paste in the following diagram definition 
     sequenceDiagram
     Alice->>John: Hello John, how are you?
     John-->>Alice: Great!
  5. Press the Packages -> Mermaid Preview -> Toggle Preview button
  6. To export as image right click the diagram and select Save as PNG

Sample Diagram in Atom

Comments