MkDocsで数式(katex)があるWebページを作成する

MkDocsにおいてKaTeXを導入する方法を説明します。

• MkDocs：markdown文書から静的Webサイトを生成するツール。mkdocs-materialと組み合わせて使うことで，美しい技術文書を作成することができる（例：https://fastapi.tiangolo.com/）
• KaTeX：数式を表示するためのライブラリ。MathJaxのほうが主流かもしれないが，KaTeXのほうが描画が速いらしい。MkDocsでMathJaxを使いたい方は，別の方の記事を参考にしてください。

こんな感じのサイトを本記事では作ります。

mkdocsの導入

pythonがインストールされているとします。pipでmkdocsとmkdocs-materialをインストールします。

pip install mkdocs mkdocs-material

次にプロジェクトを作成します。ここでは，プロジェクト名をsample_projectとします。

mkdocs new sample_project

実行すると，カレントディレクトリ直下にsample_projectフォルダができると思います。まずはビルドしてみましょう。

cd sample_project
mkdocs build

上記を実行するとsample_project/siteフォルダに，ビルド結果が出力されているはずです。index.htmlを開いて確認してください。

なお，ホットリロード機能もあります。

mkdocs serve

を実行して，http://127.0.0.1:8000/を開いてください。適当にソースコードを変更すると，自動で反映されると思います。

mkdocs-materialの導入

必須ではないですが，ずっと見栄えが良くなる（と思う）ので導入します。pipでmkdocs-materialをインストール済みとします。sample_projectフォルダにあるmkdocs.ymlを以下のように編集してください。

site_name: 'sample_project'

docs_dir: 'docs'

theme:
  name: material
  language: ja
  palette:
    primary: red

ビルドしてみると，マテリアルデザインになっていると思います。なお，言語をjaにすると，検索バーや目次などの細かい部分が日本語になります。英語でいい人は指定しなくてもOKです。primaryでサイトの色を制御できます（省略すると青っぽい感じになります）

ほかにもいろいろ変更できるので，公式サイトで調べてみてください。

katexの導入

ようやく本題。まず，markdown-katexをインストールします。

pip install markdown-katex

次に，mkdocs.ymlを再度編集してください。

site_name: 'welcome'

docs_dir: 'docs'

theme:
  name: material
  language: ja
  palette:
    primary: red

markdown_extensions:
  - markdown_katex:
      no_inline_svg: True
      insert_fonts_css: True
      macro-file: macros.tex

さらにkatexのマクロを定義するmacros.texをmkdocs.ymlと同じディレクトリに作成してください。マクロを使用しない場合は空ファイルでＯＫです。場所は変更できますが，その場合は，上記のymlファイルのパスも変更してください。以上で環境設定は終了です。

次にMarkdownファイルに数式を書いてみましょう。docs/index.mdを以下のようにしてください。

```math
f(x) = \int_{-\infty}^\infty
    \hat f(\xi)\,e^{2 \pi i \xi x}
    \,d\xi
```   

インラインで数式を書きます。$`E=mc^2`$

ビルドかホットリロードすると，冒頭の画像のようなWebページになっていると思います。

注意する点として，数式をインライン表示させる場合，qiitaなどでは$$と書くことが多いですが，markdown-katexの場合だと$``$と書く必要があります。これは，gitlabの仕様に合わせているそうです。

katex自体の書き方は，公式の Supported Functions が参考になると思います。

VSCodeでの編集

いくらホットリロード機能があるといっても，Markdownで数式を書くときは，VSCode上で作業できたほうが無難です。

その場合は，markdown preview enhancedという拡張を入れるのがよさそうです。デフォルトでkatexをサポートしています。ただしインライン表示が$$で解釈してしまうので，そのままだと以下の画像のようになってしまいます。

これは環境設定で改善できます。VSCodeでsetting.jsonを開いて，以下のように設定を追加します。

    "markdown-preview-enhanced.mathInlineDelimiters": [
        [
            "$`",
            "`$"
        ]
    ]

これで，インライン表示も正しく表示されます。

最後に

mkdocsはplantumlにも対応しています。使い方はMKDocsでUMLを表示する方法などを参考にしてみてください。よいドキュメント生活を！

本記事作成時のバージョン情報は，以下の通りです。

• python 3.7.3
• mkdocs 1.1.2
• mkdocs-material 5.5.12
• mkdocs-material-extensions 1.0
• markdown-katex 202008.1025

参考文献

• https://github.com/mbarkhau/markdown-katex
• https://squidfunk.github.io/mkdocs-material/creating-your-site/