はじめに
こんにちは。開発ドキュメントとしてwikiを使うケースはままあると思いますが、皆さんはどんなツールをお使いでしょうか。GithubやBitbucketといったサービス付属のwiki、Qiita:TeamなどのSaaS、あるいはRedmineなどのツールに付属しているwikiだったり、もしくは自ら管理するサーバにPukiwikiなどを入れて運用することもあると思います。
その類のツールを調査していて行き当たったのが、今回ご紹介するGitbookです。
Gitbookとは
- 名前にGitと付いていますが、Githubとは特に関係ありません。
- 基本的には「マークダウン形式で書いたドキュメントをhtmlに変換するツール」です。
- 変換されたhtmlをリモートのサーバに置いて閲覧することももちろん可能です。
- node.jsさえインストールされていれば、とりあえず動きます。類似ツールに国産のCrowiがありますが、こちらはnode.js+Mongodbで動作します。
.mdファイルさえあればどこにでも置けて閲覧できるので、Gitbookの方が手軽で運用しやすいかと感じています。 - 特にプラグインなど入れずにデフォルトで記事の全文検索が可能な点が、Gitbookの長所のひとつだと思います。
では早速ローカルに導入してみましょう。環境はmacOS High Sierra 10.13.6です。
nvm
node.jsのバージョン管理は他の言語やツールと異なり乱立気味のようです。macであれば、ただ試すだけならhomebrewでもよいのですが、今回はnvmを使用します。
nvm公式のドキュメントに従ってインストールスクリプトを取得・実行します。
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
実行すると、以下の2行が~/.bashrcもしくは~/.bash_profileに追記されます。
| 1 2 3 4 5 6 7 8 9 | export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 確認 $ nvm --version 0.33.11 # nvm: command not foundになる場合 $ source ~/.bashrc もしくは source ~/.bash_profile |
node.jsインストール
その時の最新LTSを入れておけば、基本的には問題ないと思います。
LTS = Long Term Supportの頭文字です。訳すと長期サポート版となるでしょうか。
node.jsと同時にnpm(node.jsのパッケージ管理ツール)も一緒に入ります。
| 1 2 3 4 5 6 | $ nvm install --lts $ nvm use --lts # 確認 $ node -v v8.11.4 |
Gitbook導入
インストール
gitbook-cliはGitbook作成をするためのコマンドラインツールです。
| 1 2 3 4 5 6 | $ npm install gitbook-cli -g # 確認 $ gitbook --version CLI version: 2.3.2 GitBook version: 3.2.3 |
初期化
initで初期化、buildで.mdファイルからhtmlを生成します。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | $ mkdir ~/gitbook && cd ~/gitbook $ gitbook init $ 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 ! # 生成されたファイルを確認 $ ls -l -rw-r--r-- 1 nomura staff 16 9 5 22:48 README.md -rw-r--r-- 1 nomura staff 40 9 5 22:48 SUMMARY.md drwxr-xr-x 5 nomura staff 160 9 5 22:49 _book $ ls -l _book/ drwxr-xr-x 12 nomura staff 384 9 5 22:49 gitbook -rw-r--r-- 1 nomura staff 6045 9 5 22:49 index.html -rw-r--r-- 1 nomura staff 568 9 5 22:49 search_index.json |
ローカルでブラウザから確認
生成されたhtmlをlocalhostで確認できます。自分だけのためのwikiであれば、これだけで事足ります。
実際にチームで運用することを考えると、Github/gitlab/Bitbucketなどにリポジトリを作成し、.mdファイルや静的ファイルをプッシュしていくことになるでしょうか。
リポジトリのコミットログ = 記事の編集履歴になるわけですね。
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | $ 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 |
起動メッセージにあるアドレス
http://localhost:4000
にアクセスしてみましょう。
作成と編集
gitbook init
したディレクトリ
~/gitbook
に新しいファイルを作成します。ファイル名は
test.md
とします。
ターミナルで
vi ~/gitbook/test.md
でもいいですし、エディタなどからGUIで新規作成してもOKです。
中身はひとまず下記の通りにしてみましょう。
| 1 2 3 4 5 6 7 | # 記事作成してみる ## タイトル 〜記事作成のテスト〜 * 本文1 * 本文2 * 本文3の1 ** 本文3の2 ** 本文3の3 |
見出し編集
ページの左側にあるのが見出しで、ここには
~/gitbook/SUMMARY.md
の内容が出力されます。見出しを編集して新規記事へのリンクを作成しましょう。
| 1 2 3 4 | # Summary * [Introduction](README.md) * [テスト記事](test.md) ← この行を追記 |
ライブリロード機能がありますので、ページを更新せずに「テスト記事」という名前のリンクが見出しに表示されます。
さいごに
いかがでしたでしょうか。wikiツールは様々ありますが、サーバにインストールするタイプを選ぶのであれば、Gitbookはかなり良さそうだと感じています。
この手のツールはサーバ移転の際のデータ吸い出しが面倒だったりするのですが、基本的にはリポジトリ上の.mdファイルさえあればよく、身軽なところがいいですね。
チャートを簡単に描画できるmermaid.jsなるものもあるそうで、設計書・仕様書などもGitbookで事足りるのではないかと期待しています。
