github-pages | Casual Developers Note

GitBookはMarkdownで簡単にドキュメントを作るのには便利です。作成したドキュメントはPDFやePub、静的サイトとして出力できます。今回は、GitBookで作成した静的サイトを無料のGithub Pagesを使って公開する方法を紹介します。

はじめに

GitBookはMarkdownでPDF、ePub、静的サイトなどのドキュメントを作成するためのツールです。Markdownで全て書くことができるので、ドキュメント作成がとても簡単になります。

Github Pagesは静的サイトを無料で公開できるGithubのサービスです。

今回は、GitBookで作ったドキュメントをGithub Pagesで公開しましょう。

GitBookでドキュメントを作る

まずは、GitBookでドキュメントを作りましょう。前提として、NodeJSがすでにインストールされている必要があります。

GitBookのインストール

GitBookをNPMでインストールします。

$ npm install -g gitbook-cli
$ gitbook --version
CLI version: 2.3.2
Installing GitBook 3.2.3
...
GitBook version: 3.2.3
$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

GitBookを初期化する

ドキュメント用のプロジェクトを作り、初期化します。

$ mkdir project
$ cd project
$ gitbook init
warn: no summary file in this book
info: create SUMMARY.md
info: initialization is finished
$ ls
README.md   SUMMARY.md

GitBookをローカルで起動する

「gitbook serve」コマンドでMarkdownが自動的にビルドされて起動します。

$ 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」にアクセスすると、ローカルでドキュメントが確認できます。

後はMarkdownのドキュメントを好きなように編集しましょう。GitBookの書き方のサンプルはGitBookのGithubにあるので参考にして下さい。

Github Pagesで公開する

作ったドキュメントを公開しましょう。

GitBookをビルドする

「gitbook build」でMarkdownのドキュメントをビルドして、静的サイトのファイルを出力します。

$ 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 1 pages
info: found 1 asset files
info: >> generation finished with success in 0.7s !

GithubにプロジェクトをPushする

Github上でプロジェクトを新規作成した後、通常のgitコマンドで作ったプロジェクトをGithubにPushします。

$ git init
[master]$ ls
README.md     SUMMARY.md    _book/
[master]$ git add .
[master]$ git commit -m 'Add GitBook.'
[master]$ git remote add origin https://github.com/{YOUR-GITHUB-ACCOUNT}/{YOUR-GITHUB-PROJECT}.git
[master]$ git push -u origin master

これでGithubにPushできました。

Github PagesにGitBookをPushする

最後に、gitコマンドでgh-pagesブランチを作り、pushします。

[master]$ git checkout --orphan gh-pages
M   .gitignore
M   README.md
Switched to a new branch 'gh-pages'
[gh-pages]$ ls
README.md     SUMMARY.md    _book/
[gh-pages]$ git checkout master
M   .gitignore
M   README.md
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
[master]$ git subtree push --prefix _book origin gh-pages

後はGithub Pagesのルール通り、「https://{YOUR-GITHUB-ACCOUNT}.github.io/{YOUR-GITHUB-PROJECT}/」にアクセスすれば表示されます。

これで公開ができました。