Mermaid is a javascript tool to generate graphics - diagrams and charts and such using markdown-like syntax. This note describes adding it into a jekyll site such as mine https://decuser.github.io

flowchart LR id1((a)) --> id2((b)) & c--> d

Flowchart Example

Resources

Installation

The installation of mermaid is straightforward and does not require a plugin. Just add the .js and .map file of your chosen distribution to your assets folder, add a script tag to the _layouts/_post.html file, and then use the appropriate incantation in your posts.

Install the mermaid-js dist files

The current version of Mermaid, at the time of this post, is 9.3.0. It is available at:

https://unpkg.com/browse/mermaid@9.3.0/dist

The files I chose to install were:

  • mermaid.js
  • mermaid.js.map
  • mermaid.min.js
  • mermaid.min.js.map

Downloading these specific files was a little tricky. So, for future reference, here’s what I did (may change over time):

  1. Browse to the dist directory
  2. Locate the file of interest - say, mermaid.js
  3. Click on its link to open it’s page
  4. Right-click on View Raw and Save Link As…
  5. Put the file where you like

Using aria2, I just downloaded them directly:

mkdir ~/Downloads/mermaid
cd ~/Downloads/mermaid
aria2c https://unpkg.com/mermaid@9.3.0/dist/mermaid.js
aria2c https://unpkg.com/mermaid@9.3.0/dist/mermaid.js.map
aria2c https://unpkg.com/mermaid@9.3.0/dist/mermaid.min.js
aria2c https://unpkg.com/mermaid@9.3.0/dist/mermaid.min.js.map

Then in the repo, I created a folder for them and copied them in:

cd ~/sandboxes-git/decuser.github.io
mkdir -p assets/mermaid-9.3.0
cp ~/Downloads/mermaid/* assets/mermaid-9.3.0

Modify _layouts/post.html and index.html

Add a script tag for mermaid into post.html and index.html just after the jekyll header:

<script src="/assets/mermaid-9.3.0/mermaid.js"></script>

Edit a post with mermaid markup

In a post, just add some mermaid markup. This creates a digraph:


<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</div>
graph TD; A-->B; A-->C; B-->D; C-->D;

Digraph Example

This creates a gitgraph:


<div class="mermaid">
gitGraph
    commit id: "First"
    commit id: "Second"
    branch develop
    commit id: "Third"
    checkout main
</div>
gitGraph commit id: "First" commit id: "Second" branch develop commit id: "Third" checkout main

Gitgraph Example

This creates a flow chart:


<div class="mermaid">
flowchart LR
     id1((a)) --> id2((b)) & c--> d
</div>
flowchart LR id1((a)) --> id2((b)) & c--> d

Flowchart Example

Test the changes

bundle exec jekyll s

browse to http://localhost:4000

Deploy the changes

git add .
git commit -m "added mermaid to site and posted"
git push

Navigate to https://github.com/decuser/decuser.github.io/actions and watch it deploy.

Test the deployment

post last updated 2023-01-23 12:13:00 -0600