github pagesとjekyllを今さら練習

思うところがあって github pages と jekyll を試してみた。

github pages

2種類ある。

  1. username.github.com
  2. username.github.com/repos

username.github.com

github.com/username/username.github.com

という repository を作る。例えば wtnabe なら

github.com/wtnabe/wtnabe.github.com

になる。ここに index.html を push してやればほどなく

http://wtnabe.github.com

にアクセスできるようになる。(これ書いてる時点ではテストが置いてあるけど、いつまでもあると思っちゃダメよ)

username.github.com/repos

各 repository に gh-pages という branch を作る

ことで、この中の HTML や素材が

username.github.com/repos

という名前でアクセスできるようになる。

両方作ったらどうなるの?

2種類あると気づいた段階でピンときてたんだけど、どうもこの2種類の github pages は最終的に一つのディレクトリツリー上に展開されているようだ。

試しにやってみたところ

  1. github.com/wtnabe/wtnabe.github.com 内に /ical2gcal/index.html を作成
    • 作った /ical2gcal/index.html が wtnabe.github.com/ical2gcal/ に表示される
  2. github.com/wtnabe/ical2gcal に gh-pages branch を作る
    • 作った gh-pages が wtnabe.github.com/ical2gcal/ に表示される
  3. github.com/wtnabe/wtnabe.github.com/ical2gcal/index.html を編集
    • 今編集したファイルが表示される。つまり 1 に戻る。

という動きをした。

つまり username.github.com の github pages を作る際には各 repos の名前空間が conflict することになるので注意が必要。

作り方

Web UI から自動生成するのが楽だし template も選べてよいと思う。

特に repository の github pages を作る際はすでにある README を index の内容として読み込んでくれる機能もあるのでだいぶ楽。README を github 標準のスタイル以外でも表示できるというだけでもそれなりに意味があるし、ちょっとドキュメント書くかって気になりそう。

jekyll

github pages と言えば jekyll というか、もう生の HTML の編集なんてできませんて。

ということでこっちも試してみる。jekyll コマンドで

  • (デフォルトで) _site/ 以下に render 結果を生成
  • –server で localhost に確認用のサーバを起こす
  • –auto でファイルを監視して自動生成
    • ただし livereload のような仕組みはないのでそこは各自で reload するか工夫が必要

という感じで使える。

以前紹介した Middleman は Sinatra を使って Rails 風の layout で、tilt を使って各種のマークアップ形式や CoffeeScript などに対応していたが、こいつはそれに比べるとだいぶシンプル。

とは言えちょっとクセがあって、

  • — で囲んでコンテンツのファイルを二層にしないと変換が機能しない。最低限 layout と title を YAML で定義する感じになると思う。
  • git や gem 関係で必要なものも放っておくと出力(コピー)される1ので、_config.yml の exclude: に定義しておくとよい
  • Textile は使わなくても RedCloth のインストールは必須で、かつ正しく依存性解決してくれない
    • ここはだいぶ変だと思う2

excludeの定義は例えばこんな感じ

exclude:
  - .git
  - .bundle
  - Gemfile
  - Gemfile.lock
  - _config.yml
  - _layouts
  - params.json
  - vendor

実はこの params.json が何してるのか、まだよく分かってない。github pages を auto generate させたら勝手にできてた。

jekyll on github pages

jekyll での生成をアテにして Markdown ファイルや _layout/ などのファイルを直接 push してやると、ほどなく render 後の正しい HTML を閲覧できるようになる。

この機能を正しく使うには localhost に jekyll の環境がないとすぐに確認できないので黒い画面が苦手な人には厳しいと思う。

逆に使わないなら jekyll は無関係に github pages は作れる。

まとめ

github pages と jekyll を同時に扱おうとして無駄にややこしくなってしまった。

github pages は単に HTML を置いておくことができる repository でその名前や branch にルールがあるだけ。

たまたま jekyll での生成をアテにしたファイルも置いておくことができるというだけ。

jekyll はー…個人的には Liquid の良さがよく分からないのと、Liquid を使いつつ Textile や Markdown だけ特別扱いしている jekyll の方針がなんかモニョモニョする。まぁ何かしら global な値を渡したりはしたいんだけど、テンプレートや値の渡し方は Middleman + Tilt の方がよさげに見える。たぶん対応を広げすぎない方がいいという判断であえて現状のような構成になってるんだろうけど。

あと github pages のドキュメント、リンクがループしてたりして全然さっくり分かる感じがしないのは割と残念。仕組みはいいのに。

リンク

  1. 例えば vendor/ 以下もそのまま! 

  2. 0.11.2時点の話 

More