A few weeks ago, I was looking into business logic and was asked to diagram what was happening in the code.

I don’t like documentation, but at the back of my mind, there is always a voice saying – “The moment you hit send, it’s obsolete” – and generally that’s true to form.

And honestly, I didn’t want to create another set of Visio diagrams where I would agonize over lines crossing each other, the color of the squares, and ensuring that each box and line lined up correctly.

Not sure how I came to it, but I found a tool called Mermaid, which blew my mind in its simplicity of use, scalability in implementation, and even more, the extensions into code and IDE, which have the potential to make your documents *gasp* actually living.

Note: I never knew about Mermaid until a few weeks ago, but I thought this was such a great tool. I have zero affiliation with the company. Right off the bat, on a Sunday, I shared it with my team and have been digging more and more into it.

The Output

Setting up a profile and going to MermaidChart, is a breeze, and in seconds, you’re churning out some pretty slick, structured diagrams.

Both Sequence and Activity diagrams are pretty straightforward, with some design elements added.

Diagram By Code

Although I could interact with the designer and drag and drop these objects onto a pane, that’s where Visio ends and Mermaid begins, because I did ZERO drag and drop and wrote this out in the simplest of syntax models

For the Sequence Diagram

sequenceDiagram
    actor MarketingUser as MarketingUser
    Note left of Topic: Triggered when a new Topic is <br>created in the system
    Topic->>+Purpose: Get Purpose based on Topic
    Purpose->>+Topic: Set local Purpose Id
    Campaign->>+Purpose: Identifying the owning Campaign
    Purpose->>+Campaign: Return the Campaign Id
    Topic->>+Topic: Update Topic with the related Campaign Id

For the Activity Diagram

---
config:
  theme: redux
  look: neo
---
flowchart TD
    A(["When a contact is updated and their emailaddress is not null"]) --> B{"Are they an active member?"}
    B --> C["Find the campaign(s) they are a part of"] & D["End"]
    G{"Are they subscribed to default topics?"} --> H["Reset their auth record back to <b>Opted-In</b>"] & I["Create an Auth record that is marked as <b>Opted In</b>"]
    I --> J["Notify the User of the updates"]
    H --> J
    J --> K["End"]
    C --> G
    style A stroke:#00C853
    style B stroke:#2962FF
    style D stroke:#D50000
    style G stroke:#2962FF
    style K stroke:#D50000

Yeah, that’s it, and to be honest, I never cranked out diagrams so fast. I was up and running with the base properties of Mermaid, cranking out code in 5 minutes, and then I started to dig further and further into the syntax to see all the cool things I could do.

In their web IDE, the code I wrote looks like this;

And once you get a handle on the syntax, you’re good to go. I love the ability to inject HTML directly into whatever you’re doing.

All in all, I probably spent about an hour generating about 5 – 6 of these diagrams and it felt as natural as coding.

Extensibility with AI

Obviously, after completing my work project, my mind started racing towards how I could link this up to a project and have it update automatically when I commit code without prompting me. Sure, I might have a line out of place here or there, but I could update that after the fact, I’d have live diagrams.

Sure enough, Mermaid is built for extensibility with a complete library of integrations to the most common IDEs (VSCode, JetBrains, Confluence, and ChatGPT) all available here.

The ChatGPT Connector integration is a thing of beauty (and it also shows what you can do when you want to get fancy).

When done through ChatGPT, you’ll get all the code generated, all from a prompt – “Create a flowchart for making pizza. Add emoji.”

GitHub Copilot Extensibility

The real value of any developer tool is not solely how it deals with your new code, but what it can do for your old code. Decades of code are not going to vanish in a single vibe session.

At the time of writing, Mermaid is going to be converting their GitHub Copilot integration on November 10, 2025, to an MCP Server implementation, so until then, you can follow the below.

Follow the instructions here for installation steps (which are basically 3 clicks).

After this, I opened VS2022 and pointed towards an old project and gave it a simple prompt;

@mermaid-chart Can you make a flowchart for my GitHub Action #AzureDevOpsWorkItemFactory?

When “Applied” or “Previewed” you get the same great document structure coming back at you.

For a tool I found by accident and bailed me out of a jam, I’m wondering how I can leverage it in a number of scenarios going forward. I’m pretty picky about tools I add to my toolbox, but Mermaid got the immediate add!

If you haven’t tried it, go get Mermaid.