MermaidJS is great because it brings graphs-as-code to the web! No longer do we need to run graphviz from the commandline to generate static image files each time we make a change; Now we see changes instantly, embed graphs with ease in source repositories and track their changes, etc..

The trouble I’ve had with Mermaid is figuring out the syntax, there are quite a few gotchas which don’t advertise themselves very clearly, such as it not tolerating blank lines, or spaces are comma-deliminated lists.. I’ll list these here so you can get graphing quicker than I did!

This is our example graph, I’ll go through all the considerations when coding this.

flowchart LR subgraph Humans Users SysAdmins end subgraph Systems webserver["Web Servers"] backend[("Backend Servers")] VPN end Humans -->|Dedicated
Connection| Systems Users -->|HTTP| webserver SysAdmins --- VPN VPN & webserver --> backend

Linking together blocks in a flowchart is achieved with the --> syntax, optionally this can have spaces eitherside -->.

Linking can occur on the same line that a block is defined, so: GitLab --> cicd where this is the first time both GitLab & cicd have been mentioned. Although to keep things tidy I generally try to keep all the linking below the subgraphs and block definitions.

Linking more than two blocks together on the same line can be achieved with an ampersand: VPN & webserver --> backend results in both VPN & webserver each being individually linked to backend.

You can see in the example graph that linking is flexible, a child element of the Humans subgraph can link against a child of the Systems subgraph and subgraphs can link to eachother.

Annotate links is as simple as inserting the text between two pipes |My Comment| at the end of the link: A -->|My Comment| B. Alternative syntax A -- My Comment --> B also exists.

Subgraphs visually group related elements and allow you to draw relationships between separate groups.

    subgraph Humans
        Users
        SysAdmins
    end
    subgraph Systems
        webserver["Web Servers"]
        backend[("Backend Servers")]
    end

Miscallaneous

  • Line breaks aren’t natively supported so we have to use the HTML <br> to insert a line break, this may not work if your MermaidJS is configured for strict security.