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

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

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

こんな感じのサイトを本記事では作ります。
![無題.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/260124/dcd43c59-ce83-edac-fc03-de07cfeec1a0.png)

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

```sh
pip install mkdocs mkdocs-material
```

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

```sh
mkdocs new sample_project
```

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

```sh
cd sample_project
mkdocs build
```

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

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

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

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

```mkdocs.yml
site_name: 'sample_project'

docs_dir: 'docs'

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

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

ほかにもいろいろ変更できるので，[公式サイト](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/)で調べてみてください。

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

```sh
pip install markdown-katex
```

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

```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](https://katex.org/docs/supported.html) が参考になると思います。

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

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

![無題.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/260124/7939992e-818c-fa81-19b2-8031e33ef169.png)

これは環境設定で改善できます。VSCodeで[setting.jsonを開いて](https://qiita.com/y-w/items/614843b259c04bb91495)，以下のように設定を追加します。 

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

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

## 最後に
mkdocsはplantumlにも対応しています。使い方は[MKDocsでUMLを表示する方法](https://qiita.com/Taka710/items/3e4a01fcc1d907967cb2)などを参考にしてみてください。よいドキュメント生活を！

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

- 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/