さて gitbook である。
2014年くらいの流行りネタな気もするが、使ってみて便利だったので自分向けのメモを残しておくことにする。
gitbook は markdown 形式で保存したテキストから下のような体裁のコンテンツを生成するサービスである。
Webサービスなのだがコマンドラインツールも提供されている。ここで扱うのはコマンドラインツールの方だ。
ドワンゴさんのScala研修テキストがこれで作成されているのをきっかけに関心を持ったもの。
インストール
gitbook-cliをインストールする。
$ npm install -g gitbook-cli
出力先としてPDFとかepubを利用したい場合、calibreもインストールする必要がある。
$ brew cask install calibre
プロジェクトの作成
プロジェクトディレクトリを作成して初期設定する。
$ mkdir my-book; cd my-book
$ gitbook init
これで SUMMARY.mdとREADME.md の二つのファイルが生成される。
設定ファイルの book.json を新しく作成する。以下では言語設定を ja にしているのと、SNS/GitHubでのシェアボタンを非表示にしている。
{
"plugins": ["-sharing","hide-published-with"],
"language": "ja"
}
book.json を作成したらプラグインのインストールを実行する。
$ gitbook install
動作確認
以下のようにすると localhost:4000 にサーバが起動し、ブラウザが起動してgitbookが表示される。
$ gitbook serve --open
最初はREADME.mdの内容(Introduction)しかないので、見るべきものは別にない。
気が済んだら Ctrl + C しておく。
最低限の設定
SUMMARY.mdに構成を書いていく
SUMMARY.mdを開き、作りたいファイル構成を想定して目次を修正する。
README.mdとSUMMARY.mdの場所は変更可能だけど、変更しない方が gitbook init した際の動作がわかりやすいので、この二つのファイル以外のいわゆる本文を適当なディレクトリに分けるととして、SUMMARY.mdを例えば以下のようにする。
# Summary
## 序文
* [この資料について](README.md)
* [対象読者](README.md#対象読者)
* [免責](README.md#免責)
## 本文
* [1. ほげほげ](contents/body-1.md)
* [2. ほげほげ](contents/body-2.md)
* [3. ほげほげ](contents/body-3.md)
## 結文
* [おわりに](contents/postscript.md)
SUMMARY.mdを編集したら、もう一度 gitbook init を実行する。そうすると、SUMMARY.md に記述されているファイルで存在しないものを自動的に作成してくれる。
$ gitbook init
info: create contents/body-1.md
info: create contents/body-2.md
info: create contents/body-3.md
info: create contents/postscript.md
info: create SUMMARY.md
info: initialization is finished
h1が見づらいのでCSSを置く
デフォルトのCSSだとh1とh2のスタイルが区別しづらいため、h1を少し目立たせることにする。
stylesディレクトリを作成し、website.cssとpdf.css、epub.cssを作成する。
$ mkdir styles/
$ echo "h1 { border-bottom: 2px solid #000; padding-bottom:3px;}" > styles/website.css
$ echo "h1 { border-bottom: 2px solid #000; padding-bottom:3px;}" > styles/pdf.css
$ echo "h1 { border-bottom: 2px solid #000; padding-bottom:3px;}" > styles/epub.css
HTMLの生成
以下コマンドで静的な html が生成される。出力先はデフォルトでは _book/ である。
$ gitbook build
gitbook serve で利用できるものと同等のものっぽい。静的なファイルへのビルドなのでS3とかに置いておけば動く。便利だ!!
念のためにPDFの生成を試す
$ gitbook pdf
出力先は book.pdf がデフォルトである。このあたりはオプションで変更できる。ちなみにpdfはかなりサイズが大きくなり、この例でいえばだいたい10MBくらいになる。
まとめ
とりあえず手元で書き始めるにはこのくらいで十分そう。
SUMMARY.md ではレベル1見出しが無視されるとか、箇条書きだけが目次として機能して地の文は無視されるとか、まあまあ癖のある挙動だけど慣れの範囲かな。
プラグインやカスタマイズがいろいろ可能なのだけど、凝り始めると肝心のドキュメントの記述に手が回らなくなってしまうので余暇でやっていこう。