GitLabで数式もプレビュー可なMarkdownブログ環境

(1) GitLab で数式を含む Markdown ファイルのプレビューを行いたい。ただし、(2) その Markdown ファイルは Web サイトやブログの原稿であるため、静的サイトジェネレータで処理できるようにしたい。また、(3) ローカルで原稿を書いている最中もそれらの数式のプレビューを見ながら作業できるようにしたい。できれば、(4) 特殊なエスケープ処理をせずに TeX の数式表現を書けると嬉しい（\{ を \\{ と書かなければならない等）。

こんな 4 つの要件を同時に満たすような執筆環境を実現できないか色々と調べていたのだけれど、どうやら Nikola なら実現できそうだ。

要点は以下の 3 点。

数式は GitLab でプレビュー可能な書式をそのまま使う
Web サイトの生成には静的サイトジェネレータ Nikola に拡張機能 markdown_katex を入れて使う
執筆環境では Visual Studio Code に拡張機能 Markdown+Math を入れて使う

１点目への補足として、GitLab がサポートする Markdown に数式を埋め込む書式を書いておこう。まず普通の（本文に埋め込まれる、インラインな）数式を書きたければ、 TeX の数式表現をバックティックで囲い、さらにそれをドル記号で囲う。たとえば:

$`e^{\pi i}+1=0`$

また独立した段落（？）としてレンダリングされる display スタイルの数式を書きたければ、 TeX の数式表現を「プログラミング言語として math を指定したコードブロック」に書く。

```math
e^{\pi i} + 1 = 0
```

正直に言えば好みではないのだけれど、この GitLab の動作は変更できないので従うしかない。

２点目の Nikola について。 Nikola は Python 製の静的サイトジェネレータで、同種のツールでは Jekyll や Hugo などが有名。これは Markdown ファイルをパースするために内部で Python-Markdown を使っているのだけれど、これに前述の数式を囲う書式を認識させる markdown_katex という拡張機能がある。ということは Nikola が Markdown を（Python-Markdown を使って）パースするときにこれを有効化できれば、GitLab で使える数式の書式が問題なく解釈されることになる（Markdown 解釈のフェーズで認識するため Markdown の書式と衝突せず、そのため \\{ などというエスケープが不要になる）。で、それを行うには Nikola の Web サイト設定ファイル conf.py で次のようなエントリーを追加すれば良い:

# conf.py
MARKDOWN_EXTENSIONS = [
    'markdown.extensions.fenced_code',
    'markdown.extensions.codehilite',
    'markdown.extensions.extra',
    'markdown_katex',  # これを追加
]

3 点目の VSCode についても補足。 Markdown+Math で GitLab の書式で書かれた数式を認識させるには設定項目 mdmath.delimiters を gitlab に設定する。なお、VSCode を再起動（あるいは Window のリロード）をしないと設定変更が反映されないことがあった。