TIL: Diagram with Mermaid on GitHub in Markdown

#mermaid #github #diagram #markdown

Mermaid is a JavaScript utility to create beautiful diagrams from text. I have read about it before, but it had been parked on the check out - eventually list.

On February 14th. GitHub announced support for Mermaid in GitHub Markdown. I decided to check it out right away, so I went to the Mermaid website, I found the online editor - which is truly awesome and started thinking about what to diagram.

I am writing up some notes on chezmoi and decided to see if I could replicate the diagram from the chezmoi documentation.

All I can say it that you very very fast can get something that looks really good.

I ran into an issues with replicating the order of the elements. Luckily the Mermaid documentation is pretty good and adding participant elements provided in the order I wanted.

You can compare the two versions:

And this is the Mermaid code:

sequenceDiagram
    participant $HOME
    participant working copy
    participant local repo
    participant remote repo
    $HOME->>local repo: chezmoi init
    $HOME->>working copy: chezmoi add <file>
    working copy->>working copy: chezmoi edit <file>
    working copy-->>$HOME: chezmoi diff
    working copy->>$HOME: chezmoi apply
    $HOME-->>working copy: chezmoi cd
    working copy->>local repo: git add
    working copy->>local repo: git commit
    local repo->>remote repo: git push
    local repo-->>$HOME: exit

When fetching the version from chezmoi I found out it was also Mermaid well I just needed a reference diagram for my experiment.

But I ran into another problem. Mermaid is supported for Markdown on GitHub, which is marvelous, but it does not seem to be supported for pages, you can compare, these two versions:

I am investigating whether I can add Mermaid to the Pages rendering, but it requires that I can control the HTML, so I would prefer for GitHub to support this out of the box.