オープンソースこねこね

Webプログラミングなどについてあれこれ。

Github Pagesでプロジェクトページを作ってみた

3ヶ月ほど前になるのですけど、PHPマイグレーションツールを作ったのです。

PHPMigrate - PHPでマイグレーションツールを作った

これはPHPファイル一つで動作する簡易マイグレーションツールで、実際にしばらく使っていたのですが、運用しているシステムが複数のDBスキーマ管理したり、同じスキーマだけど自動テスト用と開発用、本番用で接続先が違ったりと複雑化してきて、どうにも使いにくくなってきました。

とういうわけでファイル一つで動作するという手軽さは捨てて、もっと構成管理しやすくしたバージョンに新しく書き直しました。テストコードもつけてpackagistに登録してComposerでのインストールに対応させたりもしました。

LibMigration

で、ドキュメント書くついでにGithub Pagesもいじってみようと思って、ちょっと調べながらプロジェクトページを作ってみました。わりと簡単にそれっぽいページができましたよ。

f:id:kohkimakimoto:20130703011030p:plain

リポジトリ自体は自分でつけたスターいっこしかないけど、ちょっと気分がいいのでブログ書きます。

Github Pages

一応Github Pagesについて、ざっくり説明しておきます。これはGithubのリポジトリやユーザアカウントに関連付けたWebサイトが作れて、ホスティングしてくれるGithubのサービスです。

http://pages.github.com/

最初の登録方法は以下などを参考にすればいいと思います。

https://gist.github.com/weed/3608503

GithubらしいのがページのソースはGitリポジトリにコミットして管理するという点。今回私が作ったリポジトリに関連づけるページではgh-pagesというブランチが作られるので、そこにサイトのソース一式をコミット、pushする。そうして決められたURLにアクセスするとWebページを表示してくれる仕組みになっています。

また、デザインテーマに最初からかっこいいやつがいろいろ用意されています。

Jekyll

さて、このGithub Pagesですがページを編集するためのCMSみたいなものはなく、基本的には自分で生のHTMLをいじくることになります。ただGithub Pagesはサイトを表示する時JekyllというRuby製のHTMLジェネレータを通してリポジトリの内容をWebページにレンダリングしています。

Jekyllは普通のHTMLはそのままHTMLとして出力して、markdownで書いたページがあれば、HTMLにしてくれるます。またlayout機能をもっているので、デザインテンプレート部分だけHTMLで書いてコンテンツ部分をmarkdownで書くようなことができます。

プログラムのように動的にコンテンツを変えることはできませんが、共通部分を抜き出して部品化できるので、効率的にサイトを編集できます。

ページ作成を始める - ローカル仮想環境にJekyllをインストールする

さて、markdownで書いたコンテンツを確認するのにいちいちGithubにpushするのは面倒なので、 ローカルにあるCentOS仮想環境RubyとJekyllを入れて、 手元でも確認できる環境をつくります。RubyはRVMでインストールしました。以下の記事などを参考にどうぞ

http://kohkimakimoto.hatenablog.com/entry/2013/04/09/185204

Jekyllはgemでインストールするだけ。以下のコマンドを実行します。

$ gem install jekyll

ページのブランチをcloneする

ページのソースを管理しているブランチをローカルにcloneします。

$ git clone git@github.com:kohkimakimoto/lib-migration.git
$ cd lib-migration/
$ git checkout gh-pages

Jekyllの確認用のサーバを立ち上げる

Jekyllには組み込みサーバがバンドルされています。ページ編集中にこれを立ち上げておき、ファイルを更新すると随時自動でHTMLを再生成してくれてブラウザで確認できるようになります。

$ jekyll serve --watch

デフォルトでport4000でサーバが起動するので

http://192.168.56.1:4000/

とかブラウザでアクセスすればサイト表示が確認できます。

レイアウトファイルを作って、デザインとコンテンツを分離する

_layoutsディレクトリを作ってその配下にdefault.htmlというファイルを作ります。以下の様な構成でHTMLを書きます。{{ content }}となっているところが、後で別途作るコンテンツ用のページに置き換わることになります。

<html>
  <head><title>{{ page.title }}</title><head>
  <body>
    {{ content }}
  </body>
</html>

コンテンツをmarkdownで書く

index.mdを作成して以下のような感じにコンテンツをmarkdownで書きます。上部にあるlayout,titleの指定で、layoutを選択し、タイトルを差し込んでいます。

---
layout: default
title: LibMigration
---

## A minimum database migration library and framework for MySQL.

LibMigration is a minimum database migration library and framework for MySQL.
...

さらにdocumentation.mdとかcommands.mdとかページごとにmarkdownファイルを作ってコンテンツ増やしていきます。

コミットしてpush

ひと通り、ページを作成したら、コミットしてpushします。

$ git add .
$ git commit -a
$ git push origin gh-pages

キャッシュされているのかジェネレートにタイムラグがあるのか、Github Pages上ではすぐに更新内容が反映されないことがあるので、その場合はしばらく待ちます。

あとソースコードの記述をハイライトさせたかったので、jQueryjQuery Syntax Highlighterを使いました。javascriptcssもそのままコミットすればいいです。コードのハイライトは以下の様な表示に。

f:id:kohkimakimoto:20130703011025p:plain

というわけで、ひと通りの作業はこんな感じです。完成したページは以下からどうぞ。

LibMigration Github Pages