GitBook使ってみた

6415 ワード
npm ドキュメント管理 Markdown gitbook Markdown テキストリンク

はじめに

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

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

  • 環境構築が簡単
  • 気軽にドキュメントがかける
  • 記事の検索が容易

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

環境構築

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

$ npm install -g gitbook-cli

gitbook環境構築

$ 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

普通のドキュメント

フローチャート

検索

さいごに

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

  • 環境構築は簡単
  • mdのかきやすさはエディタ次第(どうやらgitbook専用のエディタ的なものもあるみたいだ)
  • フローチャート以外にもUMLなどのプラグインがあるので拡張はしやすそう
  • 目次を自分で作ったりしないといけないのがめんどくさい
  • 画像などの外部ファイルの取り扱いがめんどくさい

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

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

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

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

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

Techブログに加えて会社ブログなどもやっているので、気になった方はぜひ覗いてみてください。
https://www.wantedly.com/companies/ks-rogers