21
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

Organization

最低限の知識で gitbook を利用する

さて 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見出しが無視されるとか、箇条書きだけが目次として機能して地の文は無視されるとか、まあまあ癖のある挙動だけど慣れの範囲かな。

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Sign upLogin
21
Help us understand the problem. What are the problem?