GitBookを使ってみる

· by humangas · Read in about 1 min · (191 words)

なぜ?

見た目が良さげ&epub、PDFなどにも出力できるようなので、使ってみることにした。
どっかで、ちゃんとしたドキュメントを納品しないといけないとかいう場合に使えるかもということで。

インストール

今回はローカルで使ってみたいので、そのセットアップ手順

$ npm install gitbook-cli -g
$ gitbook --version
CLI version: 2.3.0
GitBook version: 3.2.2

–vesrionを打つと、GitBook本体もインストールされたっぽい。

calibreインストール

pdf, ebupなどに変換する場合に必要なので、インストールしておく。

$ brew install Caskroom/cask/calibre

セットアップ

$ mkdir -p ~/src/work/test-gitbook
$ cd $_
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
$ ls -l
total 8
-rw-r--r-- 1 humangas staff 16  2 27 20:44 README.md
-rw-r--r-- 1 humangas staff 40  2 27 20:44 SUMMARY.md

なるほど、init すると、READMEとSUMMARYが出来る。 適当に、Markdownファイルを足して、SUMMARYに結びつけておけばよし。

ビルド

$ gitbook build
$ gitbook pdf
$ gitbook epub

Serve

$ gitbook serve

他のテーマを使ってみる

GitBookのサイトでCreateしようとすると、デフォルトのBOOK&MANUAL以外にも利用できる模様。 ローカルでやる時には以下のようにやれば良いみたい。

book.jsonを作成する

README.mdとかと同じ階層にbook.jsonを作成する

$ cat book.json
{
    "plugins": [ "theme-faq" ]
}

プラグインをインストールする

book.jsonを読み取ってくれて、勝手にインストールしてくれる。

$ gitbook install
info: installing 1 plugins using npm@3.9.2
info:
info: installing plugin "theme-faq"
info: install plugin "theme-faq" (*) from NPM with version 1.2.1
/Users/humangas/src/work/test-gitbook
└── gitbook-plugin-theme-faq@1.2.1

info: >> plugin "theme-faq" installed with success

あとは、gitbook serve とかで起動してやると、たしかに見た目が変わった。 同じ要領でやれば、他にも拡張できるのだろう。

日本語検索対応

昔は、日本語検索が全然だめだったみたいだが、デフォルトでも引っかかるようになっていた。 とはいえ、中途半端。。

そこで、検索してみると、プラグインがあったので、追加でインスコしてみると、精度がぐっと良くなった。使えるレベルだと思う。 上記のfaqテーマに加えて、日本語検索対応を追加してみる。

$ cat book.json
{
    "plugins": [
        "theme-faq",
        "-lunr",
        "search-languages"
    ],
    "pluginsConfig": {
        "searchLanguages": {
            "lang": "jp"
        }
    }
}

$ gitbook install

GUI

brew search gitbook したら、2つ出てきた。 どちらもインスコしてみたが、以下で良いみたい(公式ぽい)。 もう一つも公式ぽいが、View用なのかな? よくわからん。

$ brew install Caskroom/cask/gitbook-editor

使い方は、見ればわかるという感じだったのでメモなし。