はじめに
こんにちは。開発ドキュメントとして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に追記されます。
node.jsインストール
その時の最新LTSを入れておけば、基本的には問題ないと思います。
LTS = Long Term Supportの頭文字です。訳すと長期サポート版となるでしょうか。
node.jsと同時にnpm(node.jsのパッケージ管理ツール)も一緒に入ります。
Gitbook導入
インストール
gitbook-cliはGitbook作成をするためのコマンドラインツールです。
初期化
initで初期化、buildで.mdファイルからhtmlを生成します。
ローカルでブラウザから確認
生成されたhtmlをlocalhostで確認できます。自分だけのためのwikiであれば、これだけで事足ります。
実際にチームで運用することを考えると、Github/gitlab/Bitbucketなどにリポジトリを作成し、.mdファイルや静的ファイルをプッシュしていくことになるでしょうか。
リポジトリのコミットログ = 記事の編集履歴になるわけですね。
起動メッセージにあるアドレス
http://localhost:4000
にアクセスしてみましょう。
作成と編集
gitbook init
したディレクトリ
~/gitbook
に新しいファイルを作成します。ファイル名は
test.md
とします。
ターミナルで
vi ~/gitbook/test.md
でもいいですし、エディタなどからGUIで新規作成してもOKです。
中身はひとまず下記の通りにしてみましょう。
見出し編集
ページの左側にあるのが見出しで、ここには
~/gitbook/SUMMARY.md
の内容が出力されます。見出しを編集して新規記事へのリンクを作成しましょう。
ライブリロード機能がありますので、ページを更新せずに「テスト記事」という名前のリンクが見出しに表示されます。
さいごに
いかがでしたでしょうか。wikiツールは様々ありますが、サーバにインストールするタイプを選ぶのであれば、Gitbookはかなり良さそうだと感じています。
この手のツールはサーバ移転の際のデータ吸い出しが面倒だったりするのですが、基本的にはリポジトリ上の.mdファイルさえあればよく、身軽なところがいいですね。
チャートを簡単に描画できるmermaid.jsなるものもあるそうで、設計書・仕様書などもGitbookで事足りるのではないかと期待しています。
