Gitbookのインストール（2016/1/19時点）
お仕事で色々と勉強している、ここには書けないことをまとめるためにいいツールはないかと探していたところ、現時点ではGitBookが良さそうだと思い、インストールしてみました。
別にTeXやExcelやWordなどでもよかったのですが、書き殴りたい時にはどれも大げさなので却下しました。GitBookならmarkdownで書けますし、目次も作ってくれるので、複数の内容を整理しつつ書くのには便利そうです。GitBookの公式サイトにある説明だとプライベートなリポジトリを持つには月額いくらかを支払う必要があるものの、本記事で説明しているローカルでgitbookコマンドをインストールして使う方法であれば、そうした制限もなく自由に使えます。
セットアップ
1. Node.jsのインストール
GitBookをインストールするには、npmが必要です。手元のマシンにはNode.jsが入っていなかったので、公式サイトからパッケージをダウンロードしてインストール。ダウンロード時のOS X向け最新版は「v4.2.4 LTS」と「v5.4.1 Stable」だったので、5.4.1をインストールします。
2. gitbookのインストール(失敗)
Node.jsのインストールにより使えリュ王にsudo npm install -g gitbookと入力してgitbookをインストール。sudoしているのは、-gオプションを付けてインストール先をグローバルにするためです。ちなみにiTerm2で実行したらプログレス表示がおかしくなっていたので、OS標準のターミナルで実行しました。
…と、インストールが終わったところで試しに起動してみたところ、次のようなエラーが出てきてしまいました。
% gitbook serve You need to install "gitbook-cli" to have access to the gitbook command anywhere on your system. If you've installed this package globally, you need to uninstall it. >> Run "npm uninstall -g gitbook" then "npm install -g gitbook-cli" %
gitbookコマンドを使うにはgitbook-cliが必要なので、gitbookはアンインストールしなさいと怒られてしまいました。しょうがないのでアンインストール。
% sudo npm uninstall -g gitbook
公式サイトを調べてみると、こちらのgitbookリポジトリにあるREADMEで正式なインストール方法が載っていました。…やはりgitbook-cliをインストールしなければいけませんでした。
ちゃんと公式文書に当たらないとだめですね・・・。
3. gitbook-cliのインストール&動作確認
ということで、怒られたgitbookではなくgitbook-cliをインストールします。
% sudo npm install -g gitbook-cli
ここでインストール完了後にgitbookコマンドを実行してみたところ、本動作が始まる前に「Installing GitBook 2.6.7」のメッセージと共にgitbookのインストールが始まりました。どうやらこのタイミングでgitbookはインストールされるようです。なるほど。
% gitbook serve Installing GitBook 2.6.7 2016-01-19 19:33:59.464 xcodebuild[5600:86029] [MT] PluginLoading: ... : gitbook@2.6.7 ../../var/folders/mc/.../T/tmp-.../node_modules/gitbook ├── bash-color@0.0.3 : └── npm@2.4.1 Live reload server started on port: 35729 Press CTRL+C to quit ... info: loading book configuration....OK info: load plugin gitbook-plugin-highlight ....OK info: load plugin gitbook-plugin-search ....OK info: load plugin gitbook-plugin-sharing ....OK info: load plugin gitbook-plugin-fontsettings ....OK info: load plugin gitbook-plugin-livereload ....OK info: >> 5 plugins loaded
ログに「Live reload server started on port: 35729」とあるので、試しにSafariで「http://localhost:35729 」にアクセスしてみました。そうしたら「{"tinylr":"Welcome","version":"0.2.1"}」と応答を確認できました。
以上でインストールは完了です。
使い始め
GitBook上でドキュメントを作成していくには、何はなくとも「SUMMARY.md」と「README.md」の2つのファイルが必要です。
| ファイル | 用途 |
|---|---|
| SUMMARY.md | 目次。ブラウザだと左ペインに表示される内容を記述 |
| README.md | 本全体、各章の冒頭に記す短めの文章。巻頭言に使う |
これらのファイルは自分で作っても良いですが、gitbook initコマンドで作成してくれるテンプレートを利用するのが簡単なので、そちらを利用してしまいましょう。
% mkdir my_greatbook && cd my_greatbook % gitbook init info: init book at /Users/username/my_greatbook info: detect structure from SUMMARY (if it exists) info: create SUMMARY.md info: create README.md info: initialization is finished Done, without error % ls README.md SUMMARY.md
この状態であれば、あとはgitbook serveコマンドで閲覧できます。
% gitbook serve [~/my_greatbook] Live reload server started on port: 35729 Press CTRL+C to quit ... info: loading book configuration....OK info: load plugin gitbook-plugin-highlight ....OK info: load plugin gitbook-plugin-search ....OK info: load plugin gitbook-plugin-sharing ....OK info: load plugin gitbook-plugin-fontsettings ....OK info: load plugin gitbook-plugin-livereload ....OK info: >> 5 plugins loaded info: start generation with website generator info: clean website generatorOK info: generation is finished Starting server ... Serving book on http://localhost:4000
そしてブラウザで「http://localhost:4000 」にアクセスします。
うまくいきました。
以降はトップフォルダでgitbook serveを実行しておくだけで、自動的にmdファイル・SUMMARY.mdの追加変更を検知して_booksの内容を更新してくれるます。ビルドだけしたい場合は「gitbook build」コマンドを使います
ずっと以前にgitbookを触ったことがあったのですが、当時は日本語のファイル名など目次がうまく取り扱えていなかったため使用を諦めていました。しかし今は軽く触ってみた限りですが何の問題もなさそうでした。もともと気軽に構造化された文章を扱える環境だったので、これは便利でいいですね。
