More than 1 year has passed since last update.

さて gitbook である。

2014年くらいの流行りネタな気もするが、使ってみて便利だったので自分向けのメモを残しておくことにする。

gitbook は markdown 形式で保存したテキストから下のような体裁のコンテンツを生成するサービスである。

スクリーンショット 2016-12-25 13.13.34.png

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でのシェアボタンを非表示にしている。

book.json
{
    "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.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くらいになる。

スクリーンショット 2016-12-25 13.14.28.png

まとめ

とりあえず手元で書き始めるにはこのくらいで十分そう。

SUMMARY.md ではレベル1見出しが無視されるとか、箇条書きだけが目次として機能して地の文は無視されるとか、まあまあ癖のある挙動だけど慣れの範囲かな。

プラグインやカスタマイズがいろいろ可能なのだけど、凝り始めると肝心のドキュメントの記述に手が回らなくなってしまうので余暇でやっていこう。

Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account log in.