2018-03-14

GitBook を使ってみる

この1年ほど更新が止まっていて、様々な Issue がほったらかしではあるものの、現状これ以上手軽なドキュメント作成ツールが見当たらない、そんな GitBook を使ってみる。

GitBook CLI をインストールする

GitBook を利用したプロジェクトの構築・開発を手助けしてくれる、gitbook-cli というパッケージがあるので、基本はコレをインストールして利用する。

今回は適当なプロジェクトを作成し、そこに gitbook-cli をローカルインストールして作業することにする。

# 適当な作業ディレクトリを作成してそこに移動する
$ mkdir gitbook-practice && cd $_
# package.json を生成する
$ npm init -y
# gitbook-cli をローカルインストールする
$ npm i -D gitbook-cli

次に、package.json の scripts ブロックを編集して、npm run gitbook で gitbook-cli のコマンドを使えるようにしておく。

{
  // …中略…
  "scripts": {
    "gitbook": "gitbook"
  }
  // …中略…
}

そしたら、以下のコマンドを実行する。

$ npm run gitbook init

すると、README.md と SUMMARY.md が生成される。コレがそれぞれ、トップページとサイドメニューになるファイルだ。

GitBook は Markdown ファイルで執筆する。最終的には HTML に変換してくれるのだが、その変換や、簡易サーバを構築してのライブリロード開発も、gitbook-cli が担ってくれる。

簡易サーバを起動するには以下のコマンドを実行する。

$ npm run gitbook serve

すると、http://localhost:4000/ で実際の表示が確認できるようになる。このままライブリロード開発ができるようになっているので、例えば README.md の内容を書き換えたりすると、それが再ビルドされて自動的にブラウザも更新される。

サーバを止める時は Ctrl + C で止められる。

簡易サーバを立ててライブリロードで執筆作業を行ったら、最後はビルドしてみよう。

$ npm run gitbook build

コレでプロジェクトルートに _book/ ディレクトリができ、その中に HTML ファイルが生成されていることが分かるだろう。

どうやら _book/gitbook/gitbook.js あたりがメニューやリンクを色々と制御しているらしく、静的な HTML ファイルをそのまま開くだけでは正常に画面遷移ができない。手間だが適当なサーバ上に配置して利用しよう。

GitBook のメニュー上部を見ると、「Type to search」というプレースホルダが見える。ココは全文のインクリメンタル検索が可能な欄。GitBook v3 あたりから機能が拡充してきたので、ぜひ最新版に近いモノを入れておきたい。
book.json という設定ファイルを用意すると、プラグイン等の管理ができるようになる。
サイドメニューとなる SUMMARY.md だが、ココに Markdown ファイルへのリンクが書かれていないと、その Markdown ファイルはビルド対象に含まれないので注意。
Mac 環境だと特に問題なく使えるが、Windows 環境だと、SUMMARY.md に記載するファイル数が増えれば増えるほど、ビルドに極端に時間がかかってしまう不具合が報告されている。残念ながら GitBook 自体がメンテナンスされなくなってしまっているので、Windows 環境で利用する際はある程度諦めないといけないかと。

その他色々と機能があって、一度には説明しきれないので、今後説明していく。