Thakker's Corner

Mermaid, Azure DevOps Wiki and Sequence Diagrams

Oct 18, 2020 | 2 minute read

Hello Folks! It’s been a while since I have blogged 😊, just have been busy with client projects.

In the meantime, I have been thinking about some of the topics that I would like to share and one of them is using Mermaid syntax in Azure Devops Wiki pages to generate Sequence diagrams.

In several of my projects, we have been using Sequence diagrams to show data flow between the architectural components and have mainly used Web Sequence Diagrams for it. But sometime back on one of my projects, I came to know about mermaid tool and found it pretty interesting. You can see that its a nifty tool that not only generates several types of diagrams as code but also integrates well with Azure DevOps Wiki Pages.

Lets look at how do we go about doing this:

Creating Azure Devops Wiki

Note: You will need the right version of Azure DevOps for this integration. For more details refer here

Once you have this verified, create a new project in Azure DevOps as shown here:

Setup

We’ll keep this setup simple so, select the Wiki tab and create project wiki.

Setup

Then, enter the title and click on the Insert Mermaid Diagram, which will generate a sample graph diagram

Setup

Setup

Understanding mermaid markdown syntax

Mermaid website has good documentation around how to get started with different diagram types and they also have a live editor, so I’ll let you explore that. For our example, we will look at the sequence diagram and the following example:

Setup

::: mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts<br/>prevail...
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
:::

Note: Any mermaid specific syntax should be between start ::: mermaid and ::: tags. From the above example, you can see that the syntax is pretty straighforward. Some quick tips below:

  • SequenceDiagram indicates the diagram type.
  • participant tells which the components in the sequence diagram.
  • -» and - -» indicate synchronous & asynchronous flows.
  • loop and Note right of John and self-explanatory.

You can refer here to learn more about the different diagrams types

So there you see it was very easy to get started with Mermaid and Azure DevOps Wiki and the best part is since this is all backed by git repo, it can be versioned and setup as part of your CI pipeline.

Setup

Related Posts