GitHub の README.md に LaTeX 記法の数式を埋め込む方法を模索しました。
動機
開発者に不可欠なサービスである GitHub において、 README.md はそのプロジェクトの有用性を伝える上で重要な役割を果たします。
その README.md を編集してゆく中で、 記法で数式を書きたくなることがあるかと思います(ないかもしれないけど)。
ただ、どうやら GitHub上の Markdown は 記法に対応してないらしく、通常のように数式を打とうとしてもレンダリングしてくれません。
↓
↓
Markdown の癖になんでだぁ~ !!?
という訳で、普通のやり方では数式を埋め込むことができないので、別のやり方で数式を入れる方法を模索しました。
注意
本記事による手法は 2020年5月25日現在可能であることを確認しております。
今後の仕様変更によりこの方法でも数式を埋め込むことができなくなる可能性はあるかもしれませんので予めご理解のほどよろしくお願いいたします。
やり方
CODECOGS を利用します。
これは 記法の数式を画像として出力してくれる Web サービスです。
このサービスが吐いてくれる数式の画像を README.md に埋め込んでやろう、という訳です。
早速このサイトに飛んでコードを書き込んでみましょう。
ここで、インライン数式モードを利用したい場合は Inlineの部分にチェックを入れます。
(今回はインライン数式モードは利用しないことにします。)
続いて、画面下の方に画像を URL 化してくれる場所があるので、URL を選択してそれをコピーします。
ここからは 2 通りのやり方に分かれます。
[方法1] HTML 記法による画像埋め込み
先ほどコピーした URL を利用して、README.md の Edit 画面に次のように書いてみます。
<img src="https://latex.codecogs.com/gif.latex?\int&space;x&space;\,&space;dx&space;=&space;\frac{1}{2}&space;x^2&space;+&space;C" />
↓
↓
出来ましたね!!
ただ、打ち込んだ のコードに大量に半角スペースがあるため、URL の中に &space;
が混在しており、少し煩雑になっています*1。
では多くの場合、半角スペースはコンパイル時に無視されるため、例えば次のように URL を修正してもうまくいきます。
<img src="https://latex.codecogs.com/gif.latex?\int{x}\,dx=\frac{1}{2}x^2+C" />
基本的に &space;
の部分を取り除くだけで OK ですが、\int
の後の x
に { }
が付いていることに注意してください。
(そうしないと \intx
と解釈されてコンパイルエラーになります。)
&plus ;
を +
にしても大丈夫です。
ここまで来ればもうお気付きになったかもしれませんが、結局のところ、README.md の Edit 画面上で
<img src="https://latex.codecogs.com/gif.latex?~~~~~~~~" />
のように書き込み、 ~~~~~~~~
の部分に普通に のコードを書けば良いということになります。
ただし、URL 中に半角スペースは置けないので、それが必要な時は &space;
を使うか、 { }
で凌ぐ必要があることに注意してください。
なお、CODECOGS で Inline にチェックを入れた場合は次のような URL が得られるはずです。
https://latex.codecogs.com/gif.latex?\inline&space;~~~~~~~~
そのため、インラインモードで 記法の数式を埋め込む場合は、
<img src="https://latex.codecogs.com/gif.latex?\inline&space;~~~~~~~~" />
のように書けばよいです。
[方法2] Markdown 記法による画像埋め込み
GitHub が に対応していないとはいえ、README.md はれっきとした Markdown ファイルなので、Markdown 記法によって画像 URL を埋め込むことも可能です。
HTML 記法の時と同様に、次のように書けば良いです*2。
![](http://latex.codecogs.com/gif.latex?&space;~~~~~~~~)
HTML の時と違い、 コードを書く部分である ~~~~~~~~
の直前に &space;
があることに注意してください*3 *4。
インライン数式モードの場合は次のように書きます。
![](http://latex.codecogs.com/gif.latex?\inline&space;~~~~~~~~)
ただし、Markdown 記法では コードの読み取りに失敗することが多く、HTML 記法による埋め込みと比較して若干使いづらい印象があります(例えば \,
が使えなかったりします)。
そのため、個人的に README.md に数式を埋め込む際は HTML 記法で書く方が良いような気がします。
結論
README.md に数式を埋め込みたい時は、
- ディスプレイ数式モードの場合は
<img src="https://latex.codecogs.com/gif.latex?~~~~~~~~" />
- インライン数式モードの場合は
<img src="https://latex.codecogs.com/gif.latex?\inline&space;~~~~~~~~" />
のように書けば良い!!