Using Mermaid diagrams with Statiq.

Introduction

Mermaid is a toolset for producing diagrams using markdown notation. Statiq is a .NET based static website generation toolset. This article details a way to integrate the pair to display diagrams inside a statically generated website.

Getting started

1. Create a .NET Core 3.1 (or NET5) console app project and add Statiq as a dependency.

   dotnet add package Statiq.Web

2. Update the Program Entry point to utilize Statiq.

   using System.Threading.Tasks;
   using Statiq.App;
   using Statiq.Web;
   
   namespace StatiqMermaid.Website
   {
       public static class Program
       {
           public static async Task<int> Main(string[] args)
           {
              return await Bootstrapper
                  .Factory
                  .CreateWeb(args)
                  .RunAsync();
           }
       }
   }

3. Mermaid has a NodeJS Command Line Interface tool which can be installed as an development dependency. You will need a recent version of NodeJS installed then you can install the CLI:

   npm install @mermaid-js/mermaid-cli -D

You're now ready to get running with Mermaid

Preparing a Mermaid Markdown file

1. Create a folder structure in your console app project of "input\img\mermaid"
2. Add a text file to the mermaid folder with an .mmd file extension. For example flowchart.mmd

3. Add the following markdown notation to the file:

   graph TD; A-->B; A-->C; B-->D; C-->D;

Transforming the Mermaid diagram to an image

1. In the folder containing your solution create a batch file along the lines of build-mermaid.cmd

2. Add the following commands:

   pushd StatiqMermaid.Website\input\img\mermaid ..\..\..\node_modules\.bin\mmdc -i flowchart.mmd -o flowchart.svg popd

Building Statiq and Viewing the result

1. In the folder containing your solution create a batch file along the lines of run-testserver.cmd

2. Add the following command:

   dotnet run --project StatiqMermaid.Website -- preview --port 30080

Going further

1. Playing with more diagrams and different image output styles and file formats.
2. Using a foreach loop in a batch file or powershell script to transfrom multiple markdown files.
3. Using a shellexecute stage during your Statiq Console app build phase.
4. Setting up a CI\CD flow to automate the build and deploy.

References

• Github mermaid-cli https://github.com/mermaid-js/mermaid-cli
• Mermaid Flowchart Sameple https://mermaid-js.github.io/mermaid/#/flowchart?id=flowcharts-basic-syntax
• MARTIN BJÖRKSTRÖM: I ported my blog to Statiq https://martinbjorkstrom.com/posts/2020-04-20-i-ported-my-blog-to-statiq