Edited at

GitBook使ってみた

image.png


はじめに

皆さん、どうもです。k.s.ロジャースのやすもんです。

弊社ではドキュメント管理にkibelaを利用しているのですが、先日社内で議論していたときにGitBook使ってみるのはどうか?という意見が出て使ってみました。(ローカルで動かすぶんにはタダですからね!)

ポイントとしては以下の3点を重要視しました


  • 環境構築が簡単

  • 気軽にドキュメントがかける

  • 記事の検索が容易

npmなどは導入されてる前提です。


環境構築

ローカルで動かす、gitbook-cliをインストール

shell

$ npm install -g gitbook-cli

gitbook環境構築

shell

$ mkdir gitbook

$ cd gitbook

$ gitbook init

Installing GitBook 3.2.3

...(中略)

info: create README.md

info: create SUMMARY.md

info: initialization is finished

という感じで、macにnpmが入っていたら上記のように一瞬で環境構築できてしまいます

簡単ですね


ノートを作る


pluginを入れる

pluginを入れることで、フローチャートなども書けるように拡張できるみたいなので、導入してみます

$ vi book.json

{

"plugins": ["new-flowchart"],
"pluginsConfig": {
}
}

pluginをインストールする

$ gitbook install

これで、フローチャートが使えるようになりました


目次を作る

SUMMARY.mdをいじり、目次を作る

# Summary


*
[Introduction](README.md)
* [Chart1](docs/chart1.md)


ノートを書く

$ vi README.md

# Introduction

## gitbook試してみる

-
hogehoge
- fugafuga

## エディタはsublで書いてる


フローチャートを書いてみる

$ mkdir docs

$ vi docs/chart1.md

フローチャート

Qiita上での表示がバグるので「\」でエスケープしてます
\``` flow
st=>start: Start|past:>http://www.google.com[blank]
e=>end: End:>http://www.google.com
op1=>operation: My Operation|past
op2=>operation: Stuff|current
sub1=>subroutine: My Subroutine|invalid
cond=>condition: Yes
or No?|approved:>http://www.google.com
c2=>condition: Good idea|rejected
io=>inputoutput: catch something...|request

st->op1(right)->cond
cond(yes, right)->c2
cond(no)->sub1(left)->op1
c2(yes)->io->e
c2(no)->op2->e
\```


画面確認

ローカルホストで開始する

 $ gitbook --port 8080 serve

普通のドキュメント

image.png

フローチャート

image.png

検索

image.png


さいごに

いじってみた感想としては以下のような感じでした


  • 環境構築は簡単

  • mdのかきやすさはエディタ次第(どうやらgitbook専用のエディタ的なものもあるみたいだ)

  • フローチャート以外にもUMLなどのプラグインがあるので拡張はしやすそう

  • 目次を自分で作ったりしないといけないのがめんどくさい

  • 画像などの外部ファイルの取り扱いがめんどくさい

結論として、弊社の規模感でもgitbookをAWS上に構築して使うのはちょっと役不足に感じた

https://www.gitbook.com/ などのホスティングサービスを利用すれば有用だと感じたが、お金かかるならkibelaでいいしな〜といった感じです

個人用のドキュメント管理などには良いかなーと思いました

gitbookの導入を検討している方の参考になれば幸いです


Wantedlyでもブログ投稿してます

Techブログに加えて会社ブログなどもやっているので、気になった方はぜひ覗いてみてください。

https://www.wantedly.com/companies/ks-rogers