gitbookでドキュメントを書く

0. gitbookのインストール

$ npm install -g gitbook-cli

1. gitbookプロジェクトの作成

$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

README.md (required: Preface/Introduction for this book)
必須：ルートのドキュメント

SUMMARY.md (optional: Table of Contents)
オプション：目次

2. 日本語化設定をする

book.jsonを作成

$ touch book.json

内容を下記に変更

{
    "language": "ja"
}

3. ビルトインサーバー

$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...

info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.4s !

Starting server ...
Serving book on http://localhost:4000

4. HTML出力

$ gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.4s !

5. 書き方

ドキュメントを入れるディレクトリを作成

$ mkdir docs

5.1 ページを作成

$ touch docs/first.md

あとはMarkdownで編集して、README.mdやSUMMARY.mdからリンクを貼る

# Summary

* [Introduction](README.md)
* [最初のドキュメント](docs/first.md)
    * [最初の子ドキュメント](docs/child.md)

5.2 画像を添付

画像を入れるディレクトリを作成

$ mkdir images
$ open images

あとはMarkdownで編集して、README.mdやSUMMARY.mdからリンクを貼る

![サンプルイメージ](./images/sample.png)

5.3 先にsummaryを作成する場合

先にSUMMARY.mdを修正

# Summary

* [README](README.md)

## 環境構築

* [バックエンド](docs/env-backend.md)
* [フロントエンド](docs/env-frontend.md)

ファイルができる

$ gitbook init
info: create docs/env-backend.md
info: create docs/env-frontend.md
info: create SUMMARY.md
info: initialization is finished

6. gitignore

# Logs
logs
*.log

# Runtime data
pids
*.pid
*.seed

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage

# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Compiled binary addons (http://nodejs.org/api/addons.html)
build/Release

# Dependency directory
# Deployed apps should consider commenting this line out:
# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
node_modules

_book/
book.pdf
book.epub
book.mobi