arXiv探訪

興味の赴くままに数学するだけ

GitHub+GitBook+VSCode+KaTeXによる数学文章作成について

数学文章をいかに実現するかは骨に印を刻んでいた太古の昔から続く人類の夢だったのですが、多くの人の努力があって今はその選択肢もかなり増えた気がします。「はてなブログ」もその一つであり、MathJaxを用いた数式処理システムが使われています。難しい設定が必要なく、数式の書ける「はてなブログ」の存在は本当に有難いものだと思います。しかも無料! (媚を売っていく)

さて、世の中にはGitHubというサービスがあるのですが、これは簡単に言うと文章のバージョン管理システムSNS機能がひっついたものです。(厳密にはGitというシステムの実装の一つがGitHubで、「はてなブログ」もGitの一種だそうです。)プログラマーやIT関連に詳しい人にはお馴染みかと思いますが、自分は少し前にアカウントを作ったものの、特に利用することもなくPDF置き場として放置していました。使い方も良く分からないし、目的も技術も無かったので当然ですね。ところが最近になって色々調べているうちに、自分のやりたいことが実現できる気がしました。そこで本腰を入れて取り組んでみようと思い立った次第です。百聞は一見に如かず、完成品はこちらです。

https://mathmathniconico.github.io/ConvergentSpace/

GitHubのページはこちらです。

https://github.com/mathmathniconico/ConvergentSpace

中身はシンプルですが、理想形をある程度実現できたように感じます。もちろん中身を膨らませることも可能ですが、Gitの良いところは誰でも編集に参加することができることです。同様のサービスにはWikiがありますが、こちらはより堅牢な感じがします。そしてこれが一番の売りですが、以下の方法では数式を高速にプレビューしながら作ることが出来ます。

以下では0.用語説明 1.具体的にどのような方法で実現したか 2.編集に参加し、プルリクを送るために必要なこと 3.私と同じことを自分のリポジトリで実現するために必要なこと について解説していきたいと思います。ちなみに環境はWindows8.1です。OSXの場合はGitがデフォルトで付いてたりするはずなので細部が違うと思います。

0.用語説明

自分も他人に説明できるほど詳しくはないですが、Gitの仕組みと用語について述べておきます。

Gitはバージョン管理システムであり、多人数でプロジェクトを作ることに向いています。このプロジェクトの構成ファイル群がある場所をリポジトリと呼びます。Gitはリポジトリを一元管理するのではなく、複数のリポジトリ間の調整を行う仕組みを持っています。まずリモートリポジトリと呼ばれる元締めがどこかのサーバー(GitHubなど)にあり、各ユーザーは自前のマシン上にローカルリポジトリと呼ばれるそのクローン(複製)を作ります。リモートとローカルの連携をサポートしてくれるのがGitです。

ファイルの編集はローカルリポジトリ上で行いますが、この変更はすぐには反映されません。ある程度機能を追加した段階でまずコミットします。コミットによりローカルに更新履歴を追加し(多分)、Gitの前準備をします。準備が整ったらローカルの内容をリモートへプッシュします。そしてリモートからプッシュされた内容をプルリクエストします。「こういう変更をしたいんだけどいいか?」と他のユーザーに聞く訳です。「いいんじゃないか?」と全体の総意が取れたらリモートの管理者がマージ(結合)します。ダメなら却下されます。これらの作業は全て記録され、Gitが自動的にやってくれます。これによりユーザーはリポジトリの内容のみに集中することができるのです。

1.具体的にどのような方法で実現したか

GitHubは今回の主役で、リモートリポジトリの役割を担います。ついでにSNS機能があって、芝を生やすことが出来ます。芝は草ですが生やすのは芝です。

GitHubPagesGitHubに付属しているサービスであり、自前のウェブページをリポジトリ毎に作ることが出来ます。大抵はそのリポジトリに関するドキュメントになっていることが多く、中にはブログとして使っている人もいるそうです。

GitHubDesktopGitHubをローカルで利用するためのフロントエンドです。コマンドを打ったり難しいことをしなくて済むので私のような素人には便利なソフトウェアです。

Visual Studio Code泣く子も黙るMicrosoft社純正のソースコードエディタです。多機能だけでなく拡張機能が豊富で、しかもデザインがかっこいいです。(ただしアイコンは除く。)IDEではないためデバッグコンパイルは別途に諸々が必要です。

Markdown+MathVSCode拡張機能で、markdownファイルを数式のプレビューをしながら記述することができます。プレビューにはKaTeXが使われています。

KaTeXはなんか高速に数式を表示できる謎ライブラリです。「はてなブログ」ではMathJaxを使用していますが、レンダリングが酷く遅いという問題点があります。KaTeXは出来ることは少ないですが、速度面でモバイル端末に効果が高いので夢のある技術です。

ここから先は3節で必要になるものです。

GitはGit機能をフルに使うためのバックエンドです。GitHubDesktopにはコマンドラインがないので、Git付属のGitBashで色々やります。

Node.jsが何かは全く知りません。npmというパッケージ管理ツールを使用するために必要だそうです。

GitBookGitHubとは無関係のソフトウェアで、markdown形式の文章をドキュメント型のウェブページに変換することができます。これはGitHubPagesを通して公開することができます。大事なのは、GitBookにはKaTeXを使用するためのプラグインがあることです。

2.編集に参加し、プルリクを送るために必要なこと 

まずはGitHubのアカウントを作ります。名前と、メールアドレスを登録すれば作れるはずです。実はこれだけでもう編集に参加することができます(多分)。リポジトリを開き、docs_src/README.mdSUMMARY.mdGitBookの構造に則って記述します。見て分かるように、数式のコードが見慣れない様式になっています。これは苦肉の策というか、数式の解釈がGitBookとVSCodeで異なるので、後々LaTeXコンパイルしたくなったときに置換しやすい形式にしたためです。

$${}$$がインラインの数式です。行の先頭には必ず文字を入力して下さい。(28日追記:インラインの数式は$$で良くなりました。ただ自分はVSCodeで色分けを綺麗に行いたいので${}$で囲っています。)

 
$$
\displaystyle ~
$$
 

が別行立ての数式です。(こちらをVSCodeで色分けする方法は現時点では分からないです。)上下に必ず一行を開けます。GitBookを通して別行立てにするには、この記法がベストだと思います。

変更を保存してプルリクを送ると、その内容を見て私が暇なときにマージします(多分)。

このままでは編集が大変なので、数式をプレビューしながらできるようにしましょう。

GitHubDesktopをインストールして、GitHubDesktopからログインします。そしてリポジトリをクローンして複製をローカルに作成します。(GitHub側でリポジトリをforkしていないと表示されないそうです。)クローンされる場所はUser/Document/GitHub以下だと思います。

次にVisual Studio Codeをインストールして、拡張機能からMarkdown+Mathを探してこれもインストールしておきます。ここで重要なのはFile->Preferences->Settingsで設定ファイルを開き、Extensions->mdmath->Delimiterskramdownに変更します。(28日追記:デフォルトのdollarsでも大丈夫になりました。)これで上記の書き方でもプレビューが上手く行きます。あとこれは必須かは分かりませんが、TextEditor->Files->EolLFに変更します。

あとはローカルのリポジトリから例えばREADME.mdを開けば数式をプレビューしつつ編集ができます。

編集が終わったら保存し、GitHubDesktopの左下にコメントを書いてコミットします。これでローカルに編集履歴が残ります。そして右上のプッシュを押します。プッシュしたらGitHubに戻り、プルリクエストを出せば終了です(多分)。

3.私と同じことを自分のリポジトリで実現するために必要なこと

自分のリポジトリでも同様のウェブページを作りたいと思ったら以下を実行します。

まずリモートの環境を整えましょう。GitHubリポジトリを作成します。ライセンスは好みですが、とりあえず一番緩いMITを選択しておきます。

次にGitに行き、Gitをインストールします。これは好みの問題ですが、私はGitのコマンドをGitBash専用にしました。そうせずにPATHを通せばGitHubDesktopからもコマンドが打てるようになるかもしれません。

更にNode.jsをインストールします。これでnpmが使えるようになります。そしてGitBash上でnpm install gitbook-cli -gを実行します。ほどなくしてGitBookがインストールされるはずです。またnpm install -g katexを実行します。これでKaTeXもインストールされるはずです。

さて、ローカルリポジトリdocs_src/フォルダを作り、その中でGitBashを起動して

touch README.md
touch SUMMARY.md
touch book.json

を実行します。これらのファイルが作られるだけです。ここでbook.jsonVSCode上で開き、

{
    "plugins": ["katex@git+https://github.com/gaoxiaosong/plugin-katex.git"]
}

を入力します。(28日追記:katexの最新バージョンをGitで取得し、プラグインをgaoxiaosong氏のものに変更しました。)

ローカルリポジトリdocs/フォルダを作ります。docs/docs_src/がある状態でGitBashを起動し、gitbook build docs_src docsを実行します。自動的にdocs/以下にhtmlファイルが作られるはずです。

最後にローカルリポジトリ.gitignore.nojekyllを加えます。.gitignoreには

node_modules
_book

を追加しておきます。(これらのファイルはGitの管理対象外とする。)

作成したページをテストするには一手間が必要になります。自分も嵌ったのですがdocs/にあるhtmlファイルを開いてもハイパーリンクが上手く機能しませんでした。これは自分でローカルサーバーを立てることで解決します。docs_src/でGitBashを起動し、gitbook serveを実行します。そしてブラウザでhttp://localhost:4000にアクセスすれば見ることが出来ます。

これで準備が整いました。整理すると

Repository
- docs/
    (GitBookが生成したファイル群)
- docs_src/
    - _book/
        (GitBookが生成したファイル群)
    - README.md
    - SUMMARY.md
    - book.json
- .nojekyll
- .gitignore
- README.md(GitHubによって生成されたもの)
- LICENSE(GitHubによって生成されたもの)

という感じになっているはずです。これらをGitHubDesktopでコミットし、プッシュします。

最後にリモートの設定をします。リポジトリSettingsタブを開き、master docs/をGitHubPagesとして指定します。これでhttps://USER.github.io/REPOSITORY/に目的のウェブページが作られます。

https://mathmathniconico.github.io/ConvergentSpace/

所感

色々試行錯誤の結果なので、これが最善ということはないです。もっと良い方法はあると思いますが、それなりにやりたかったことができたので満足しています。とはいえまだ理想とは程遠いので、今後さらに改良が進むことを期待したいと思います。不満点は結構あって、

  • 目次に数式が使えない。(スタイルファイルを弄ればいいかも?)
  • 数式から始まる文章を作れない。(ディスプレイモードになってしまい、後ろの文章を読んでくれない。)
  • デリミタ? の仕様が酷すぎる。(インライン・ディスプレイ両方で同じ$$を使う。)(28日追記:解決しました。)
  • 先に数式を処理するためか、コード内に$$を置けない。
  • newcommandできないが、これは仕方ない。
  • 可換図式が書けないのは致命的な人がいるかもしれない。
  • 微妙に数式が上下に伸びてる気がする。あと大きさが微妙。(設定を弄れば直るかもしれない。)

最後になりましたが、以下のサイトは凄く参考になりました。というかVSCodeでプレビューすることを加えただけで、ぶっちゃけパク・・・。 mizukami234.hateblo.jp

28日追記:GitBookのKaTeXプラグインにおけるデリミタの仕様は、同様に悩んでいる人がいたみたいです。公式は放置されてるので、gaoxiaosong氏が修正プログラムを提供してくれていました。