HUGOサイトでMermaid記法

blog
目次

Markdown 記法と同様なテキストフィルでフォローチャート等を記述できる mermaid という記法がある。これを Hugo のサイトで使用できるようにする設定。

目的

GitHub のサポートでにわかに注目を集めたMermaidを Hugo のサイトでも使用できるようにする。

例えば、私の毎日をグラフにすると

  flowchart LR
    家==>職場
    職場-->Q{お腹空いた?}
    Q==>|Yes|ダイエー
    Q-->|No|ジュンク堂
    ジュンク堂-->ダイエー
    ダイエー-->家

となります。

方法

mermaid記法を使用するためには、mermaid.jsを読み込んで動的にレンダリングさせます。

個別のページのときだけmermaid.jsを読み込むようにテーマのテンプレートを修正したいのですが、今回はグローバルのテンプレートファイルbaseof.htmlを編集しました。

baseof.htmlを編集するときは、themesにあるファイルを直接編集しません。

  1. サイトのトップにlayouts/_defaultフォルダーを作成します。
  2. 作成したフォルダーにテーマのlayouts/_defaultにあるbaseof.htmlをコピーします。
  3. baseof.htmlの下の方にmermaid.jsを読み込む設定を記載します。
<body>
  ....
  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
  <!-- <script>
		window.onload = function() {
			mermaid.init(undefined, ".language-mermaid");
		};
	</script> -->
  <script>
    mermaid.initialize({ startOnLoad: false });
    mermaid.init(undefined, ".language-mermaid");
  </script>
</body>

mermaid.jsは、どちらの方法でもmermaidブロックを解析するようになりました。

欠点

Hugoの売りは、静的サイトのため事前に作成したあるファイルを転送するだけなのでファイルの転送や作画が非常に速いことです。

しかし今回の変更により、mermaidライブラリの読み込みとクライアント側での作画時間が発生します。そのため僅かではありますが、今までよりも画面表示に時間がかかります。特にmermaid記法を使用したページが多くないので、余計にもったいない気もします。

使用例

目的に書いた「私の毎日」は、次のようにブロックとして記述してあります。ただしこの時に、ブロック内の言語としてmermaidを指定します。するとブロック内がレンダリングされて、上記のようなグラフとなります。

  flowchart LR
    家==>職場
    職場-->Q{お腹空いた?}
    Q==>|Yes|ダイエー
    Q-->|No|ジュンク堂
    ジュンク堂-->ダイエー
    ダイエー-->家

Mermaid 記法の詳しい文法は、Mermaid のページを参照してください。

基本的に、一行目にどのような図を描きたいかと、上から下か(TD)、左から右か(LR)を指定します。

その後にノードの名前と矢印でつないでいきます。ただ順番によっては意図した接続にならないことがあります。

他のアプリでの使用例

Typora

Mermaid は、お気に入りの Markdown エディタTyporaでも使用することができます。

使用方法は、Hugo のページを記載したときと同じようにブロックの言語として mermaid を使用するだけです。

RStudio

その他には、RStudio でも使用することができます。その際には、DiagrammeRライブラリーを読み込みます。

その後は、次のようにmermaidコマンドの引数として mermaid 記法の文字列を与えます。この時、引数が拡張子がmmdのファイルパスだと、そのファイルに記載した内容がmermaidへの入力と解釈されて作図されるとのことです。

library(DiagrammeR)

mermaid("
graph LR
  A-->B
  A-->C
  C-->A
")