TIL: Diagram with Mermaid on GitHub in 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:

• TIL on chezmoi using Mermaid
• chezmoi documentation

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:

• GitHub
• jonasbn.github.io

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.

Resources and References

1. GitHub Announcement on Mermaid in Markdown
2. Mermaid website
3. Mermaid online editor
4. TIL on chezmoi (GitHub)
5. TIL on chezmoi (GitHub Pages)
6. chezmoi documentation

This was lifted from my TIL collection on GitHub