asciidoctor-katex を使ってみた

# 概要

asciidoctor-katex で一応数式の表示ができたので、参考です。
なお、万人にお勧めできるものではありません。(このことは一番最後に書きます。)

## インストール

環境: Ubuntu18, ruby 2.5.1p57, Asciidoctor 1.5.8

```console
$ gem install katex
$ gem install asciidoctor-katex
```

## AsciiDoc文書のサンプル
KaTeX用の初期化コードですが、少なくとも CLI (asciidoctor -r asciidoctor-katex …) で実行した感じだと自動で突っ込んではくれないようです。

```asciidoc
= KaTeX sample
:stem:

ifeval::["{backend}" == "html5"]
[pass]
++++
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.0/dist/katex.min.css" integrity="sha384-BdGj8xC2eZkQaxoQ8nSLefg4AV4/AwB3Fj+8SUSo7pnKP6Eoy18liIKTPn9oBYNG" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.0/dist/katex.min.js" integrity="sha384-JiKN5O8x9Hhs/UE5cT5AAJqieYlOZbGT3CHws/y97o3ty4R7/O5poG9F3JoiOYw1" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.0/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>
++++

endif::[]

== インライン数式
latexmath:[E=mc^{2}]

== 円の面積

[stem,latexmath]
++++
\begin{aligned}
\text{半円の面積} =
\dfrac{S}{2} & =\displaystyle\int_{-\frac{\pi}{2}}^{\frac{\pi}{2}} \sqrt{r^2 - r^2 \sin^2\theta}\cdot(r\cos\theta)d\theta \\
&=r^2 \displaystyle \int_{-\frac{\pi}{2}}^{\frac{\pi}{2}} \cos^2\theta d\theta
\end{aligned}
++++
```

## コマンドライン

```console
$ asciidoctor --backend=html5 -r asciidoctor-katex -o katex.html katex.adoc
```

## レンダリング結果

![katex.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/326797/317debd0-8bf5-f770-cbf5-da6cfbf0a633.png)

## まとめ
個人用の数式メモなどの用途で、ifdef 入れてもいいよ……という人がデメリットの影響が少ない気がします。ifdef で分けておけば、もっとよい代替手段が見つかったときに乗り換えが楽ですし。

* asciidoctor-mathematical と比べるとインストールの面ではお手軽
* KaTeX の Starter を埋め込みが必要なのは管理上煩わしい

### メリット・デメリットの詳細

* プロジェクトが活発でない
  * Contributer が一人で、かつ活発さがない(最終更新が4ヶ月前)
  * CLIは初期化コードに関しては中途半端な出来だし、どんどん良くなる見込みもなくて、積極的に使用するような状況ではない。
* 一応、CLIでも表示はできるが、公式の例の通りだとうまくいかなかった  
  作者は、Node.js の方に興味があるのかもしれない(推測)
* KaTeX用のコードを埋め込む必要があって、手軽さに欠けるしAsciiDocのドキュメント自体がKaTeX依存の文書になる。
  * `ifeval::["{backend}" == "html5"]` でKaTeX用のコードを分けようとしても、MathJaXも同じバックエンドなので分離不可。`-r asciidoctor-katex -a use-katex` として、 `ifdef::use-katex[] ～ endif::[]` みたいに分離しないといけない。
* asciidoctor-mathematical との比較
  * インストールの手間は asciidoctor-katex の方が楽 (というより、asciidoctor-mathematical のインストールが非常にお手軽さに欠ける)
  * 表示も asciidoctor-katex の方が綺麗 (asciidoctor-mathematicalだと underbraceなどがきちんと表示できなかったりする)
  * オフライン利用は、asciidoctor-mathematical の方が有利

### ifdefのコード例
オプション指定の例

```asciidoc
ifdef::use-katex[]
[pass]
++++
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.css" integrity="sha384-zB1R0rpPzHqg7Kpt0Aljp8JPLqbXI3bhnPWROx27a9N0Ll6ZP/+DiW/UqRcLbRjq" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/katex.min.js" integrity="sha384-y23I5Q6l+B6vatafAwxRu/0oK/79VlbSz7Q9aiSZUvyWYIYsd+qj+o24G5ZU2zJz" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/mhchem.min.js" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.11.1/dist/contrib/auto-render.min.js" integrity="sha384-kWPLUVMOks5AQFrykwIup5lo0m3iMkkHrD0uJ4H5cjeGihAutqP0yW0J6dpFiVkI" crossorigin="anonymous"
        onload="renderMathInElement(document.body);"></script>
++++
endif::[]
```

KaTeX で表示するとき

```console
$ asciidoctor --backend=html5 -r asciidoctor/katex/treeprocessor -a use-katex -o katex.html katex.adoc
```

MathJaX で表示するとき

```console
$ asciidoctor --backend=html5 -o mathjax.html katex.adoc
```

## 参考

* [jirutka/asciidoctor-katex: Asciidoctor extension for converting ... - ](https://github.com/jirutka/asciidoctor-katex)
* [KaTeX – The fastest math typesetting library for the web](https://katex.org/)  
  -> Installation に Starter template の初期化コードがある
* [Asciidoctor KaTeX 2](https://github.com/cirosantilli/asciidoctor-katex-2)  
  試していない。最近できたプロジェクトのよう。サーバサイトでレンダリングする方向。