A picture is worth a thousand words. It’s easier to explain the architecture and data flows with diagrams, than with lengthy paragraps.

Developers like to stick to their text editors. Mermaid lets them create flowcharts, sequence diagrams, pie charts and many more diagrams in a declarative way.

Previously I created my diagrams in external editors, it was not the best experience to load and export data compared to writing down what I want to show up in the image and have it instantly.

Mermaid can export the generated images as .png, .svg or even .pdf.

Github announced first level support for mermaid diagrams this february. It was the first time I heard about this library, I’ve been wanting to try it eeveer since. Now I finally got a chance to draw some flowcharts.


Mermaid docs defines the basic syntax with simple examples.

Basic flowchart example

Flowchart example Flowchart example
%% single line comment
flowchart LR
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    subgraph grph[Decision graph]
        C -->|One| D[Result one]
        C -->|Two| E[Result two]

Let’s see what we got here:

  • flowchart followed by orientation
    • TB / TD - top to bottom
    • BT - bottom to top
    • RL - right to left
    • LR - left to right
  • Any single word by itself is a new node
  • The nodes can be connected together by edges
  • The text on nodes and edges can be customized
  • Single line comments start with %%


The docs has more info on styling.

Basic styling example

Styling example Styling example
flowchart LR
  classDef className fill:#f9f,stroke:#333,stroke-width:4px;


Mermaid has a command-line interface available on github.

# Convert Mermaid mmd Diagram File To SVG
mmdc -i input.mmd -o output.svg
# Create A PNG With A Dark Theme And Transparent Background
mmdc -i input.mmd -o output.png -t dark -b transparent


Mermaid has powerful syntax. If you host your code on github, your mermaid diagrams can appear without any further configuration. Otherwise you still have thee option to generate the images with a CLI tool.

Happy coding!

Cover Photo by C1superstar from Pexels