Edited at

GitBookを使ってみる

ブログ記事のコピーです。

とあるサービスのドキュメントを拝見した際に「Published with GitBook」と書いてあって「GitBookとはなんぞや?」となったので調べてみました。

どうやら「Markdownの書式で書いたドキュメントをイイ感じにHTML(Webで閲覧するためのドキュメント)に変換してくれる」ツールのようです。

文章量が多くなってしまったKiribi UsusamaREADME.mdを分割・整理するのにちょうど良さそうな感じでしたので、試してみました。


1. GitBookインストール

まずはインストールです。Node.jsが直かnかnvmかnodist辺りでインストールされていることを前提として、ドキュメントを作成したいディレクトリまで移動します。

その後、そのディレクトリ下にてnpmでGitBook(gitbook-cli)をインストールします。

> npm install gitbook-cli

次に、gitbook initコマンドを実行します。

> gitbook init

Installing GitBook 3.2.3

## 略

これで少し待てばインストールが完了します。


2. 初期設定

続いてbook.jsonを作成し、言語指定を日本語にします。

{

"language": "ja"
}

ひとまずこれだけ。


3. コンテンツ作成

さて、ここからは実際に作りたいドキュメントの中身を作成します。

1.のgitbook initコマンドでルートディレクトリにREADME.mdSUMMARY.mdが作成されています。README.mdは最初に表示されるドキュメント、SUMMARY.mdは左側のサイドバーの目次になるようです。

そのため、下図のようなディレクトリ構造とし、mdファイルを作成します。

SUMMARY.mdにはdocsディレクトリに存在するファイルへの相対パスを記述します。


4. ビルトインサーバーでテスト

コンテンツ内容が整ったらビルトインサーバで表示を確認します。コマンドはgitbook serve

> 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 5 pages
info: found 5 asset files
info: >> generation finished with success in 1.1s !

Starting server ...
Serving book on http://localhost:4000

末尾にhttp://localhost:4000にアクセスするように記載されていますのでアクセスします。

OKです。

SUMMARY.mdから生成されたサイドバーも無事に動いていることが確認できました。


5. ビルド

最後はgitbook buildコマンドでビルドします。

> 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 5 pages
info: found 5 asset files
info: >> generation finished with success in 1.1s !

ビルドすると、_bookディレクトリ以下にHTMLなどが生成されます。後はこのディレクトリ以下をアップすればオンラインマニュアルとして使えそうです。

使いどころとしては、例えばCMSのオンラインマニュアルなどをこれで構築するとWordからPDFを作成したりするよりは効率化できるのではないか、と思いました。


参考