https://enu23456.hatenablog.com/entry/2022/11/21/190642

はじめに

この記事では、「MKDocsでMermaidを使う方法」について書いています。

最近MKDocsを使って資料を書く機会が多いのですが、テキストで様々な図表を書くことができるMermaidをMKDocsで使いたいときはどうするのだろうと思ったのが記事を書いたきっかけでした。

自分に向けた備忘録の意味もありますが、「MKDocsでMermaidを使ってみたい」な人の一助になれば嬉しいです。

要点だけ

ymlファイルに以下の記述を足してください

site_name: My Docs

theme:
  name: 'material'

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

extra_css:
  - https://unpkg.com/mermaid@8.0.0/dist/mermaid.css

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

試してみた内容

まずは、下のymlファイルで作成した（ただテーマにmaterialを適用しただけの）MKDocsで表示を確認します。

site_name: My Docs

theme:
  name: 'material'

表示は以下の図の通りです。Flowchartの節にmermaidで記述したコードがありますが、図表化されずにコードのままになっています。

さて、次はmermaidが図表化されるよう、上のymlファイルに少し加筆してみます。ymlファイルの内容は以下の通りで、markdown_extensions:以下が追加されています。

site_name: My Docs

theme:
  name: 'material'

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

extra_css:
  - https://unpkg.com/mermaid@8.0.0/dist/mermaid.css

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

こちらのコードでMKDocsの表示を確認すると、無事にmermaidで書いた部分が図表化されています。

なお、テーマにmaterial使う場合は、extra_css:やextra_javascript:を省略して以下のように書くこともできます。

（materialは、ページにmermaidコードブロックが含まれている場合、JavaScript ランタイムを自動的に初期化するそうです。）

site_name: My Docs

theme:
  name: 'material'

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

しかし、デフォルトのテーマ(mkdocs)や'readthedocs'の場合には上手く表示されないので、色々なテーマも試すよという方はextra_css:やextra_javascript:を省略せず書く方が良いかもしれません。