技術と魚

雑感と備忘録

GitHub Pages + GitBook + KaTeXで数式があるドキュメントをいい感じに作る方法

開発tips

[重要] GitBookはv2になってからkatexをpluginとして使えなくなっているようです(2019/06 現在)

docs.gitbook.com

"being considered to be implemented" と言っているので、将来出来るようになっている可能性があります。

背景

輪読系の勉強会のノートを一般公開しようと思ったところ、数式を出力することを考えると、はてなやQiitaか自前か〜というところしか思いつかなかったんだけど、GitBookにKaTeXプラグインを突っ込むと出来るということが分かった。しかもGitHub Pagesに乗っければ基本Markdownで、数式も使いつつ、さらに他の人と共同でメンテ可能にし、章分けもいい感じに出来てしまうということが分かってしまったので共有してみる。

GitBookの利用例としてReduxの公式サイトがある。また、gitbook.ioというホスティングサービスもあるんだけど、数式が正しく表示されないみたいなので、ビルドしてGitHub Pagesに上げるというのが現状ベストなソリューションであろうという結論に至った。

手順

1. 適当にgithubにリポジトリを作る

(省略)

2. GitHubのSettingsから master docs/ をGitHub Pagesとするように指定する

3. ローカルのリポジトリ環境を用意

  • git initしてremote originほげほげ
  • node_modulesを.gitignoreしておくと良い

4. Gitbookに必要なものをインストール

$ npm install -g gitbook-cli

5. 適当にディレクトリを切ってREADME.mdやSUMMARY.mdを作成

$ mkdir src
$ touch src/README.md
$ touch src/SUMMARY.md

ドキュメントのソース作成時は以下を参考に。

  • mdファイルの役割についてはこちら
  • katexによる数式の挿入はこちら

6. src/book.json を作り、pluginsにkatexを指定

src/book.json

{
  "plugins": ["katex"]
}

7. GitHub Pagesがjekyllだと思わないようにするためにルートに.nojekyllを置いておく

$ touch .nojekyll

8. gitbookのドキュメントをビルド

$ gitbook install
$ gitbook build src docs

9. うｐ！

サンプル: https://mizukami234.github.io/stochastic-calculus-for-finance-note/

うむ、中々綺麗だ。

ちなみに

  • ローカルでも gitbook serve src とやれば localhost:4000 に立ててくれるので簡単に編集できる。
  • KaTeXの他にmathjaxというのがあるけど、KaTeXの方が速いらしい。