はじめに
GitBook
GitBook とは
GitBook は markdown エディタの一種です。独自の拡張書式を使うことで、簡単に美しい文書をつくることができます。PDF, ePub, mobi or HTML への出力に対応しています。
GitBook 公式の見解は次のとおりです。
GitBook is a modern documentation platform where teams can document everything from products to internal knowledge-bases and APIs. We want to help teams to work more efficientlyby creating a simple but yet powerful service for them to share their knowledge. Our mission is to make a user-friendly and collaborative product for everyone to create, edit and share knowledge through documentation.
引用：What is GitBook - GitBook Documentation
日本語訳は次のとおりです。
GitBookは、製品から社内のナレッジベースやAPIに至るまで、チームがあらゆることを文書化できる現代的なドキュメンテーションプラットフォームです。 私たちは、チームが知識を共有するためのシンプルかつパワフルなサービスを作ることで、チームがより効率的に仕事ができるようにしたいと考えています。 私たちのミッションは、誰もがドキュメントを作成し、編集し、知識を共有できるような、ユーザーフレンドリーでコラボレーティブな製品を作ることです。
Translated by DeepL
その他に以下のような特徴があります。
Web ブラウザからでなく、ローカルで独自拡張の markdown 形式で記述して Github にプッシュ → GitBook に反映ということもできたりします。今回は紹介しないので、興味のある方は Qiita にある以下記事がわかりやすそうなので参考にしてみてください。
サインアップ
まずは GitBook にサインアップします。以下のリンクから GitBook のトップページへ飛んでくだい。
Get Started を押下します。
任意のユーザー名を入力してください。組織名を入れたい場合は、あとから設定で追加できるようです。
Google アカウントや Github アカウントでサインアップすることもできるのでそのあたりは適宜指示にしたがってください。
使ってみる
実際に使ってみます。
スペースの作成
まずはスペースを作ります。このスペースひとつが一冊の本になると思ってもらって問題ないです。公開／非公開が設定できるので、任意の値を選択し、Create を押下します。
チュートリアル
スペースができたら新規文書のページが開きます。Guide を押下するとチュートリアル用のページが新規作成されます。
チュートリアル用のページにはいくらか情報が記載されています。ヘッダ、パラグラフ、コードブロックなどがひとつひとつパーツとなっていて、文書を書くときには、必要に応じてパーツを追加、デザインを選択、記述という流れを踏みます。
ヘッダの例です。パーツの左方にプルダウンメニューがあります。ここでパーツの種類を変更したり、ヘッダレベルを変更したりすることができます。
コードブロックの例です。コードブロックでは各言語に応じたシンタックスハイライトを選択することができます。
コードブロックにはファイル名（ここでは hello.sh）を追加することも可能です。
ヒントの例です。マニュアルなんかでよく使う Info, Worning, Danger, Success といったパーツが揃っています。
その他、リストや引用、表、数式などさまざまなパーツが用意されています。もちろん画像を挿入することも可能です。
Github の連携
文書作成時にはバージョン管理がしたくなるものです。ページ左方の Integrations タブから Github をオンにすると Github に用意したレポジトリを使ってバージョン管理することができるようになります。
List all repositories を押下し、レポジトリの一覧を取得します。
レポジトリの一覧が表示されたら、使用したいレポジトリを選択します。
レポジトリが大量にある場合は、右上の検索ボックスから探すこともできます。
ブランチが別れている場合はどのブランチを GitBook とリンクするか選択します。今回はプライベートでひとりで利用するためブランチを切る予定はないので master とリンクします。
同期の方向を選択します。今回は GitBook で編集した結果を Github レポジトリに動悸したいので右を選択します。
成功するとつぎのようなメッセージが表示されます。
新規文書の作成
自分でいちからページを作ってみましょう。新規ページを作成するには左ペインの New から New Page を選択します。ブランクのページが表示されるので任意のタイトルを入力します。
新しくパーツを挿入したいときは ＋ ボタンを押下します。パーツのタイプを選択して記述していけば OK です。
ヘッダとタイトルを入れてみました。
文書の保存
文書の変更は、左方 Edits タブの DRAFTS から保存します。コメントを入れて Save を押下すれば OK です。この Save は、まだ GitBook 内で保存された状態です。
Github リポジトリへのマージ
Save が完了するとボタンが Merge に変化します。Merge を押下すると Github レポジトリに変更が反映されます。
Merge 完了後に Github レポジトリをみるとたしかに反映されていることがわかります。
PDF 出力
無料アカウントではできないのですが、ページ右方のメニューから PDF 出力ができます。
PDF 出力すると以下サンプルのような美麗な書籍ができあがるようです。
参考：Front-end Developer Handbook 2016 · GitBook (Legacy)
言語設定の変更
左方の Design タブから言語設定を変更することができます。 いまいちわからないのですが、メニューなどが日本語化されるわけではなく、文書をパブリック公開したときに日本語として認識されるようです。
文書の構造
文書はグループ化したりネストすることができます。
おわりに
技術書典 8 向けに技術書を執筆していて思ったのですが、自分には markdown や Re:View 形式のようなテキストベースで文書を書くのが向いていないと思いました。
ブログのようなメモレベルであれば markdown は適しているのですが、シンプルなだけに機能不足です。Re:View も素晴らしいと思うのですが、プレビューが弱いのでいちいち PDF 出力して確認というのが正直面倒でした。
最終的に Word で書いたのですが、やはり GUI でかけるというのは視認性が高く、仕上がりが常に見えますし、ページ数などの全体ボリュームも把握しやすかったのでこちらのほうが向いていました。
しかし、Word だとスタイルを整えるのが面倒ですし、バージョン管理も難しいです。
そこで何かないかなと探していて行き着いたのが GitBook となります。しばらく試してみてうまくいきそうであれば次のイベントは GitBook で書いちゃおうかなと思います。
以上
