Hugoでmermaid記法のグラフを表示する方法

唐突ですが、このブログはHugoで作成しています。
記事の中でmermaid記法でグラフを表示したいと思ったため、
方法を調べて設定しました。
せっかくなので設定する際に調べた内容を書いておきます。

Hugoでmermaid記法のグラフを表示する方法

まず検索すると公式ドキュメントがヒットしました。それに従って設定をしていきます。
リンクは↓です。

https://gohugo.io/content-management/diagrams/#mermaid-diagrams

設定方法

Hugoはデフォルトでは、mermaid記法のグラフ表示をサポートしていません。
ですが、公式ドキュメントに記載がありました。 code block render hookを使えば良いとのことです。親切に手順が書いてあるので、code block render hookが何か理解していなくても設定できました。

1. code block render hookの作成

Hugoのテーマにlayouts/_default/_markup/render-image.htmlを作成します。

<pre class="mermaid">
  {{- .Inner | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

初めファイル名をrender_code_mermaid.htmlと間違えていたため、設定が反映されませんでした。
調べたところファイル名がrender-codeblock-xxx.htmlの形式でcode block render hookを認識しているようです。
なので、render-codeblock-mermaid.htmlというファイル名を間違えると設定が反映されません。
要注意です。

詳しくは下記を参照してください。

https://gohugo.io/render-hooks/code-blocks/#examples

Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
layouts/
└── _default/
   └── _markup/
       ├── render-codeblock-mermaid.html
       ├── render-codeblock-python.html
       └── render-codeblock.html

2. mermaidのスクリプトを読み込む

あとは、mermaidのコードブロックを含んだページにmermaidのスクリプトを読み込むように設定します。テーマのlayouts/partials/head.htmlに以下のようなスニペットを記述します。
実際には、最終的にレンダリングされたhtmlでスニペットが読み込まれていれば良いので、どのテンプレートに記述しても良いと思います。特にこだわりがなければ、layouts/partials/head.htmlに記述すると良いと思います。

{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

3. mermaid記法をmarkdownで記述

こんな感じで記述します。

  ```mermaid
  sequenceDiagram
      participant Alice
      participant Bob
      Alice->>John: Hello John, how are you?
      loop Healthcheck
          John->>John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail!
      John-->>Alice: Great!
      John->>Bob: How about you?
      Bob-->>John: Jolly good!
  ```

以下のように表示されます。

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

余談

mermaidのコードブロックがグラフとして描画されるので mermaidの記述をどうやって書こうか迷いましたが、
コードブロックをネストさせて、内側のコードブロックに記述することで表示できました。
初めその発想がなかったので、調べてみて方法が分かった時「その手があったか」と目から鱗でした。