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.jsonscripts ブロックを編集して、npm run gitbook で gitbook-cli のコマンドを使えるようにしておく。

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

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

$ npm run gitbook init

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

GitBook を簡易サーバ上で起動する

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

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

$ npm run gitbook serve

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

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

GitBook をビルドする

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

$ npm run gitbook build

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

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

GitBook のアレコレ

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