Falling in love with a mermaid

Charts as code sounds great

It's the 14th of February, and rather than buy any useless stuff I don't need for a fake holiday, I thought I'd play with a charting library. I have only recently discovered Mermaid, an awesome way to create charts using what they describe as "Markdown-inspired syntax" and I love the idea of being able to version control diagrams.

ER diagrams are an obvious use case for me

This is a somewhat questionable example, but you get the idea.

erDiagram
          MERMAIDS |o..|{ FAIRYTALES : "sometimes appear in"
          TEXT_EDITORS }o..|{ CHARTING_TOOLS : "can perform as"
          CHARTING_TOOLS }|..|{ LIBRARIES : "depend on"
          FAIRYTALES }o..o{ LIBRARIES : "are found in"

The above diagram can be rendered using the following lines of code:

erDiagram
          MERMAIDS |o..|{ FAIRYTALES : "sometimes appear in"
          TEXT_EDITORS }o..|{ CHARTING_TOOLS : "can perform as"
          CHARTING_TOOLS }|..|{ LIBRARIES : "depend on"
          FAIRYTALES }o..o{ LIBRARIES : "are found in"

It does flowcharts too!

Scribbling ideas on paper, or on a whiteboard, is something I find valuable, but it's something I mostly do for my own benefit. When it comes to sharing these works of art with collaborators, I'm often the only one that can reliably decipher them. So having a way to version control, and render them on demand, is quite useful.

graph LR
    A(Idea) -->|scribble| B{Is this legible?}
    B -->|No| C[Think about what could have been]
    B -->|Yes| D[Make a million dollars]

In practice

I've never really gotten on with tools like Visio. I fell at the first learning curve hurdle and it didn't help that I was usually asked to do something with it as an afterthought at the tail end of a project. There are scores of lighter options, both desktop- and browser-based, but nothing compares to being able to create these diagrams from within the editor of your choice.

I've been using them a lot recently to get my head around a new BI setup at work that relies on a lot of nested SQL views (I know). I found using the flowchart type to be a really simple way to document the different layers the data goes through as I've been working through the code without having to leave my editor. Another advantage is how easily they can be embedded in markdown documentation right there in the repository we are working on.

graph TB
    subgraph staging
    datasource_1 --> |load| staging_1
    datasource_2 --> |load| staging_2
    datasource_3 --> |load| staging_3
    end
    subgraph transformation
    staging_1 --> |transform| dim_1
    staging_2 --> |transform| dim_2
    staging_3 --> |transform| fact_1
    end
    dim_1 --> |join| reporting_view
    dim_2 --> |join| reporting_view
    fact_1  --> |join| reporting_view
    subgraph reporting_layer
    reporting_view --> reports
    reporting_view --> dashboards

    end

You can make them much prettier than I've shown here

There is syntax for adding colour and nested elements of charts in subgraphs, as I've illustrated above, as well as using Font Awesome icons. An easy way to get started—with examples of all the chart types—is the mermaid live editor, which renders charts as you edit them.

Using them in VS Code and GitLab

I'm using a VS Code plugin that can render them in the preview pane, but it doesn't support all the features, unfortunately. Meanwhile, GitLab automatically renders charts embedded in markdown files; GitHub doesn't currently support this. That said, there's a cross-browser plugin that will do that for you.

Publishing them in a Gridsome site

Finally, there's a plugin for Gridsome that renders them at build time; I used it to embed them in these blog posts. This is much easier than trying to mess around with diagrams in binary formats when publishing. I did run into problems trying to get a Gantt chart to render nicely though.

I love this approach

Overall, I find Mermaid's approach to creating diagrams perfect for different bits of my workflows, and they are supported across multiple platforms thanks to a wealth of third-party tools. I'm glad I finally adopted them.