MkDocsのMermaidにハマった

PyMdown Extensionsのpymdownx.superfencesを公式ドキュメントの記載通りに設定してmermaidを書いたら、mkdocs serveでは正常に動作するものの、mkdocs buildでは動作しませんでした。

そのときに解決した方法を記載します。

結論

Mkdocs-Mermaid2プラグインを使いましょう。

インストール

pip install mkdocs-mermaid2-plugin

設定方法

方法1方法2

プラグインに記載する。

mkdocs.yml

plugins:
    - mermaid2

superfencesに適用させる。

mkdocs.yml

markdown_extensions:
    ...
    - pymdownx.superfences:
        custom_fences:
            - name: mermaid
              class: mermaid
              format: !!python/name:mermaid2.fence_mermaid

状況説明

mkdocs.ymlには以下のように定義していました。

mkdocs.yml

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

extra_javascript:
  - https://unpkg.com/mermaid@10.6.1/dist/mermaid.min.js

以下のように書き、mkdocs buildすると、ページを開いたときにmermaidを書いた箇所がシンタックスエラーになります。

```mermaid
graph LR
    hello --> world
    world --> again
    again --> hello
```

原因調査はしていません。

Mkdocs-Mermaid2プラグインを使うと回避できるので、解消だけしたい方は結論に記載した方法をお試しください。