asciidoctor-katex を使ってみた

概要

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

インストール

環境: Ubuntu18, ruby 2.5.1p57, Asciidoctor 1.5.8

$ gem install katex
$ gem install asciidoctor-katex

AsciiDoc文書のサンプル

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

= 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}
++++

コマンドライン

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

レンダリング結果

まとめ

個人用の数式メモなどの用途で、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のコード例

オプション指定の例

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 で表示するとき

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

MathJaX で表示するとき

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

参考

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