Skip to content

feat: adds mermaid chart rendering plugin

Megan Filo requested to merge render-mermaid-charts into main

Related: #108 (closed)

Changes in MR

This adds markdown-it-mermaid and the mermaid.js dependency to the blog project.

We use the Markdown-It to render Markdown on our blog posts. Markdown-it does not have any native-Mermaid rendering plugin, so we have to use an Open Source library. Those options are limited. In addition, Mermaid.js version 8.8.4 MUST be used, and not a newer version, due to the way Markdown-It-Mermaid imports the dependency.

The plugin must render on the client-side, so there is a brief flicker from when the page is loaded -> the mermaid chart appears in plain text -> and then the JS correctly renders and styles the charts. It is looking for a specific mermaid CSS class.

Usage notes

We render blog posts as a single chunk of Markdown, meaning we do not render these Mermaid charts individually in separate components. This complicates things a little bit and is making the Mermaid plugin(s) tricky to use.

Notes:

  1. The backticks (```mermaid) work best with sequenceDiagram and graph types.

  2. This version of mermaid.js errors out if you add actor to sequence diagrams. I had to switch these instances to participant. Not really a big change here other than it swaps out stick figure diagrams for boxes.

  3. The HTML (<pre class="mermaid">) is crucial to get the flowchart type to work. That doesn't seem to play well with the backticks.

```mermaid

<pre class="mermaid">

</pre>

Testing

Review App Production
https://render-mermaid-charts.about.gitlab-review.app/blog/2020/07/28/container-security-in-gitlab/ https://about.gitlab.com/blog/2020/07/28/container-security-in-gitlab/
https://render-mermaid-charts.about.gitlab-review.app/blog/2021/09/08/write-vulnerability-detection-rules https://about.gitlab.com/blog/2021/09/08/write-vulnerability-detection-rules
https://render-mermaid-charts.about.gitlab-review.app/blog/2023/06/20/contributions-to-latest-git-release/ https://about.gitlab.com/blog/2023/06/20/contributions-to-latest-git-release/
Edited by Megan Filo

Merge request reports