ラック
Home > ブログ > 記事 > 2018年10月 > GitBookを使ってみる

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ファイルを作成します。

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にアクセスするように記載されていますのでアクセスします。

ビルトインサーバでGitBookの表示確認

OKです。

ビルトインサーバでGitBookの表示確認2

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を作成したりするよりは効率化できるのではないか、と思いました。

参考

タグ: javascript,単語・用語,Markdown,Node.js

 



関連する記事一覧