MKDocsでUMLを表示する方法

3816 ワード
Python3 mermaid.js Python MkDocs plantuml Python テキストリンク

MkDocsでUMLを表示する方法について

MKDocsはPython製のドキュメントサイトジェネレータです。
簡単に構築できる上に、マークダウンで書けるので、
ちょっとしたドキュメントの静的サイトを構築するのに便利です。

そうなると、Mermaid.jsやPlantUMLでUMLを表示したく
なる場面も多いと思います。

MKDocsなら、ちょっと設定を行うだけで
表示が可能となります。

MKDocsの構築は省略しますが、
以下のパッケージをPyPIからインストールしておく必要があります

pip install pymdown-extensions

Mermaid.jsの設定方法

mkdocs.ymlに以下の設定を行うだけです。

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

extra_css:
  - https://unpkg.com/[email protected]/dist/mermaid.css

extra_javascript:
  - https://unpkg.com/[email protected]/dist/mermaid.min.js

superfencesで、コードブロックの名前がmermaidとなっているものを
class名をmermaidと設定した

にすることで
描画を実現できるようです。

描画した結果は以下の通りです。

PlantUMLの設定方法

  1. PyPIよりplantuml-markdownをインストールする
pip install plantuml-markdown
  1. mkdocs.ymlに以下の設定をする
markdown_extensions:
  - plantuml_markdown:
      server: http://www.plantuml.com/plantuml

plantuml-markdownは描画を行うためのサーバを
設定する必要があります。

尚、サーバはローカルにも構築することができ、
dockerコマンドで簡単に作成可能です。

PlantUML Server

上記のように、設定を行うだけでUMLを表示させることができます。

MKDocsはテンプレートも多く、大変使いやすいドキュメントサイトジェネレータですので
ぜひ、使ってみてください。

<参考サイト>
https://github.com/squidfunk/mkdocs-material/issues/693
https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
https://github.com/mikitex70/plantuml-markdown