Diagrams for your code with Mermaid

Do you see this diagram? I used it in the AWS CDK: Querying CloudFront logs in AWS Athena (via Glue) post.

Here’s its source code (editor):

flowchart
    AWSUser["AWS user"]
    S3Logs["S3 bucket (logs)"]
    AWSAthena["AWS Athena"]
    AWSGlueTable["AWS Glue Table"]

    AWSUser <-- Runs an SQL query --> AWSAthena
    AWSGlueTable -- Provides queryable data --> AWSAthena
    S3Logs -- Is configured as\ndata source --> AWSGlueTable

Do you perceive how straightforward it is to generate a pretty diagram from just several lines of text?

That’s the power of the open-source diagram library Mermaid. I still meet people who have never heard of its existence, and I cannot stop spreading the knowledge about it because it is a pure game changer for documentation.

It has been integrated natively into GitHub for a couple of years now and is, by far (IMHO), the most straightforward way to embed visual knowledge together with your code. All you have to do is create a code block in a markdown file and use the ```mermaid tag to open the block.

Say that you’re creating a simple diagram about AWS Lambdas, and you want to categorize certain blocks as a Lambda function. You can have styles with classes:

flowchart TD
    classDef lambda fill: orangered, color: #fff

    SNSTopic
    %% Apply the custom style to the block
    LambdaListenerSNS:::lambda
    SQSQueue
    SNSTopic --> LambdaListenerSNS
    LambdaListenerSNS -- Push message --> SQSQueue

And you get (editor):

You can easily use links too (editor):

flowchart LR
    Its["It's"] --> All
    All --> About --> Us
    click Us "https://www.youtube.com/watch?v=6yP4Nm86yk0"

I use Mermaid mostly only for flowchart diagrams, but this library also supports A TON of other kinds of diagrams (examples):

JUST A TINY LIST

It’s all out there for the taking. It is just so easy nowadays to embed diagrams with your code and documentation, Do It! The value of your work will skyrocket if everyone can understand better what you’re doing! 🔥

P.s. I hope you noticed I linked a bunch of times the AMAZING LIVE EDITOR they provide. You can use it to craft diagrams, export them, and save them as SVG/PNG/whatever, all in one place. Again, open source.

No matter what you do, it looks good.

ARROWS (Me)

You can find me on LinkedIn!