読者です 読者をやめる 読者になる 読者になる

まちいろエンジニアブログ

南池袋のWebサービス開発会社、株式会社まちいろのエンジニアブログです。

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

GitHub GitBook

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

ブラウザから http://localhost:4000 にアクセスすると、ドキュメントが閲覧できます。

f:id:mkudo-machiiro:20160915094247p:plain

GitBook からドキュメントの HTML を出力する

gitbook build を実行すると、Markdown から HTML を生成することが出来ます。

第1引数には、Markdown が配置されているディレクトリを指定します。
現在の GitHub Pages は docs/ 配下にある HTML をホスティング可能なため、 docs/ 配下に出力するように第2引数にを指定します。

$ npm run gitbook build ./ docs/ 

無事出力されたら GitHub に push しておきます。

GitHub Pages を有効にする

GitHub の [Settings]-[Options]-[GitHub Pages] ページにアクセスし、Source に master branch /docs folder を選択して【Save】ボタンをクリックします。

f:id:mkudo-machiiro:20160915101355p:plain

画面がリロードされ、GitHub Pages の URL が表示されれば成功です。アクセスすると GitBook のドキュメントが表示されます。

f:id:mkudo-machiiro:20160915101611p:plain

まとめ

GitBook + GitHub Pages で、Markdown ドキュメントを簡単に公開することができました。

肝心のブートキャンプ用資料ですが・・・まだ書き途中です。 が、お試しで公開してみています。

bootcamp

今後も公開できるものは少しずつ GitBook で書いていこうと思います。