View on GitHub

akkunchoi.github.com

Jekyll + github pages を使って git + markdown でサイト構築

github pagesとJekyllを使って個人サイト構築してみました。今ご覧のこのページがまさにそうです。

はじめに

git + markdown でのサイト管理が便利そうなので、ホスティングまでできるgithub pagesを使ってみました。

ちなみにOctopress, Jekyll bootstrapを使えばもっと簡単に設置できるとみたいです（後で知った）。

[username].github.com の取得

まずは github pages のユーザーページをセットアップ。

  1. Github の Create a New Repo へ。

  2. Repository name に [username].github.com と入力。[username]は自分のIDです。

    “username = 自分のユーザID” でない場合はドメインのルートにならず、パスを切るようです。 例えば akkunchoi.github.com/hoge.github.com になる。

  3. 普通にリポジトリを作成する。

     mkdir username.github.com
 cd username.github.com
 git init
 touch README
 git add README
 git commit -m 'first commit'
 git remote add origin git@github.com:username/username.github.com
 git push -u origin master

  4. リポジトリページの Admin から GitHub Pages 内の Automatic Page Generator で適当にテーマ選択。

    自分のユーザIDをドメインにした場合（ID: akkunchoiならakkunchoi.github.com）はGeneratorのデータが自動的にmasterにマージされたが、そうでない場合は gh-pages ブランチに作成された。 また、README から HTML 作成ができるので、ペライチでいいなら Jekyll 使わなくてもいい。

  5. 以上で github pages のセットアップ完了。

  6. masterにpushすることで、自動的にデプロイされます。成功した場合は Page Build Successful というGithubからの通知が来ます。

Jekyll を使う

Jekyll のインストール

HTMLを全て自分の手で書き換えるだけなら、以上でOKです。 markdownでHTML作成するためにJekyllを使用します。

インストールはgemから。

$ gem install jekyll

最初rvmで動作させていたのを忘れて、sudo gem install jekyllしてしまった。すると、違う場所に保存されたり、root権限になってたりでややこしいことになったが、uninstall して、sudo せずに install で問題なくインストールできた。

Jekyll 用にファイルを配置する

最低限必要なファイルは次の通り。

/
|-- _config.yml
|-- _layouts
     `-- default.html

_config.yml の内容はこんな感じで。設定オプション一欄

auto: true
server: true
markdown: kramdown

当サイトの場合、default.html には Auto Generator で生成されたHTMLを元に作成しました。コンテンツ部分を ｛｛ content ｝｝ に置き換えるだけです。（全角ブラケットを半角に…）

この作業には Radium Softwareさんの リポジトリを参考にしました。

ページを作成してみる

index.md を作成します。

---
layout: posts
---

## トップページです

....

--- で囲まれた部分はページのメタデータです。layoutは必須です。タイトル、カテゴリ、タグなども設定できます。詳細はYAML-Front-Matter。

jekyllを起動

$ jekyll

http://localhost:4000 で表示できればOKです。

公開

push するだけでOK。 Github pagesが内部でJekyllを動作させて、生成してくれます。http://[username].github.com/ で表示されていれば完了。

ただ、動的な出力を行うプラグインを入れていたり、使用できない処理を入れると失敗すことがあります（Page build failure）。

Octpressは、静的HTMLをローカルで生成してアップロードしている。動的な出力を行うプラグインを動作させるためにはこの方法にするか、自分でホスティングするしかなさそう。

gh-pagesでもJekyllプラグインを使う

gh-pagesで Jekyll プラグインを使うことはできません。でもプラグインを自分のローカル環境で動作させて、生成されたHTMLファイルをアップロードすることは可能です。

  • srcブランチにmarkdownファイルなどのソースを配置
  • deploy シェルスクリプト を作成。jekyllが生成した _sites を master にコピー
  • masterには生成後のHTMLのみ配置
  • masterには .nojekyll ファイルを置いて、gh-pages側で Jekyll が動作しないようにしておく。

詳しくは 当サイトのリポジトリ を見てもらえれば良いかと思います。

他わかったこと、メモ

  • _config.ymlに設定した変数はテンプレート内では site.hoge で取得できる。
  • layout: nil でレイアウトなし出力できる。
  • テンプレートエンジン Liquid デザイナー用マニュアル
  • Liquidの raw を使用すると Page build failure （ダブルブラケットが入力できない！）。