カテゴリー: BackEnd

markdownで書けるドキュメントツールのGitbookを試す

1 はじめに
2 Gitbookとは
3 nvm
4 node.jsインストール
5 Gitbook導入
6 作成と編集
- 6.1 見出し編集
7 さいごに
8 参考

はじめに

こんにちは。開発ドキュメントとして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に追記されます。

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のパッケージ管理ツール)も一緒に入ります。

$ nvm install --lts
$ nvm use --lts

# 確認
$ node -v
v8.11.4

Gitbook導入

インストール

gitbook-cliはGitbook作成をするためのコマンドラインツールです。

$ npm install gitbook-cli -g

# 確認
$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

初期化

initで初期化、buildで.mdファイルからhtmlを生成します。

$ 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ファイルや静的ファイルをプッシュしていくことになるでしょうか。
リポジトリのコミットログ = 記事の編集履歴になるわけですね。

$ 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の1
** 本文3の2
** 本文3の3

見出し編集

ページの左側にあるのが見出しで、ここには~/gitbook/SUMMARY.mdの内容が出力されます。見出しを編集して新規記事へのリンクを作成しましょう。

# Summary

* [Introduction](README.md)
* [テスト記事](test.md) ← この行を追記

ライブリロード機能がありますので、ページを更新せずに「テスト記事」という名前のリンクが見出しに表示されます。

さいごに

いかがでしたでしょうか。wikiツールは様々ありますが、サーバにインストールするタイプを選ぶのであれば、Gitbookはかなり良さそうだと感じています。
この手のツールはサーバ移転の際のデータ吸い出しが面倒だったりするのですが、基本的にはリポジトリ上の.mdファイルさえあればよく、身軽なところがいいですね。
チャートを簡単に描画できるmermaid.jsなるものもあるそうで、設計書・仕様書などもGitbookで事足りるのではないかと期待しています。