GitBook で作成したドキュメントを GitHub Pages で公開する

f:id:mkudo-machiiro:20160915102741p:plain:w400

こんにちは、まちいろの工藤 (@macococo) です。

以前本ブログにて『まちいろブートキャンプの取り組みについて』という社内研修の紹介記事を書きましたが、
最近そのブートキャンプ用の資料を GitBook で作成して GitHub Pages で公開してみたので、今回はその手順を紹介したいと思います。

GitBook とは？

www.gitbook.com

GitBook とは、Markdown で記述したドキュメントを HTML や PDF に変換することができるツールです。

HTML に変換できるため、HTML をホスティングすることができる GitHub Pages と組み合わせることで、Pull Request フローを通して文章作成をしつつ、ドキュメントを公開することが可能です。

GitBook 用のリポジトリを作成する

まずは GitHub に GitBook 用のリポジトリを作成し、ローカルに clone しておきます。ここでは gitbook-sample という名称にしました。

$ git clone git@github.com:mkudo-machiiro/gitbook-sample.git

次に gitbook-cli をインストールします。

$ cd gitbook-sample
$ npm init
$ npm install gitbook-cli --save

gitbook コマンドが実行できるよう、package.json の scripts を編集します。

{
  "scripts": {
    "gitbook": "gitbook"
  }
}

gitbook init コマンドでリポジトリを初期化します。成功すると、目次にあたる SUMMARY.md と、コンテンツに当たる README.md が自動で作成されます。

$ npm run gitbook init
> gitbook-sample@1.0.0 gitbook /Users/mkudo/dev/sandbox/gitbook-sample
> gitbook "init"

warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

gitbook serve を実行すると、Web サーバーが起動します。

$ npm run gitbook serve

> gitbook-sample@1.0.0 gitbook /Users/mkudo/dev/sandbox/gitbook-sample
> 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 1 asset files
info: >> generation finished with success in 0.7s !

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