Help us understand the problem. What is going on with this article?

GitBookを使ってみる

More than 1 year has passed since last update.

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

とあるサービスのドキュメントを拝見した際に「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を作成したりするよりは効率化できるのではないか、と思いました。

参考

arm_band
フルスタックエンジニアっぽい何か。LAMPやNodeからWP、gulpを使ってejs,Scss,JSのコーディングまで一通り。たまにRasPiで遊んだり、趣味で開発したり。
https://labor.ewigleere.net/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした