ローカル環境でGitBookを作成、閲覧できるようになるまで

5824 ワード
Markdown gitbook Markdown テキストリンク

概要

GitBookはマークダウンで書かれたドキュメントに目次などをつけてHTMLに変換することで、閲覧しやすくするコマンドラインツールです。
ビルドしたドキュメントを簡単にオンラインに公開できるそうです。
GitbookIO/gitbook: 📝 Modern documentation format and toolchain using Git and Markdown

本記事でやること

この記事では、ローカル環境でマークダウンドキュメントを作成、GitBookでビルドし閲覧できるところまで実行する手順を記します。

実行環境

  • MacBook Pro(Retina 13-inch, Early 2015)
  • OS X El Capitan
  • git v2.10.1
  • node v8.5.0
  • npm v5.3.0

準備

node.jsをあらかじめインストールしておきます。
今回はすでにインストールがされていたので飛ばしますが、検索するとたくさんの記事が出てきます。

GitBookをインストール

$ npm install gitbook-cli -g

対象ディレクトリでbookを作成する

bookにしたいディレクトリに移動し、以下のコマンドを入力します。

$ gitbook init .

すると、以下の2ファイルが新規作成されました。

  • README.md
  • SUMMARY.md

ビルドしてみる

gitbook initを実行したディレクトリ内で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"... O
info: found 1 pages
info: found 3 asset files
info: >> generation finished with success

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

このような表示がされてサーバが立ち上がりました。

gitbook initで生成されたSUMMARY.mdは以下のようになっているので、これを編集してbookを作成していきます。

SUMMARY.md
# Summary

* [Introduction](README.md)

今回検証用に用意したディレクトリ構成は以下のようにしました。

~/gitbook_install
.
├── README.md
├── SUMMARY.md
├── sample1
│   ├── README.md
│   └── hoge.md
├── sample2
│   ├── README.md
│   └── poyo.md
└── sample3
    └── fuga.md

これを反映させるためにSUMMARY.mdを編集します。

SUMMARY.md
# Summary

<!-- リンク記法で目次を作成 -->
* [introduction](README.md)

<!-- カテゴリ分けのようなこともできる -->
### category1

* [sample1](sample1/README.md)
    * [hoge](sample1/hoge.md)
      <!-- '#'でページ内にアンカーを作成することもできる -->
      * [hoge](sample1/hoge.md#hoge)

* [sample2](sample2/README.md)
    * [poyo](sample2/poyo.md)


### category2

* sample3
    * [fuga](sample3/fuga.md)

すると以下のようなbookが作成できます。

まとめ

ページ内で素早く検索ができたり、ドキュメントの閲覧が便利になりそうなので、普段作っているMarkdownドキュメントでもGitBookを活用できたらなと思いました。
最低限閲覧できるところまでしかしていないので、もっと便利な使い方や見逃している部分があったら指摘いただけたら嬉しいです。

参考資料

Installation and Setup · GitBook Toolchain Documentation

Pages and Summary · GitBook Toolchain Documentation

GitBookローカル開発環境セットアップ - Qiita