おもこん

おもこんは「思いつくままにコンピュターの話し」の省略形です

Jekyllを勉強中（５）

GitとGitHub Jekyll Webアプリ、テクニック

今回は、github-pagesというgemについて書きます。

Gemfileの利点

前回（「Jekyllを勉強中（４）」）Gemfileを使ってJekyllを動作させる上で必要なgemを指定しました。 実際に追加されるgemはGemfileに書いたものより多く、10以上のgemが追加されることが多いです。 これをいちいちインストールする手間を考えれば、GemfileとBundlerの便利さが分かります。

しかし、それだけではありません。 最も重要なことはバージョン管理をサポートしていることです。 Gemfileでは、gemの後に、そのバージョンを指定することができます。

gem 'abcd'
gem 'efgh', '3.0.0'
gem 'ijkl',  '>=1.0'
gem 'mnop',  '~>2.1'
  • abcdは、最新のものがインストールされる（バージョン指定無しの場合）
  • efghはバージョン3.0.0のものがインストールされる
  • ijklのバージョン1.0以上のものがインストールされる
  • mnopはバージョンが2.1以上で3.0未満がインストールされる。 ~>では、最後のドットの前は変わらない。 例えば~>1.2.3.4は1.2.3.4以上1.2.4`未満。

公開されたRubyプログラムがGemfileを持っていれば、それをダウンロードした誰もが同じバージョンを使うことになります。 それによって、バージョンの違いによる誤動作を防ぐことができます。

github-pages

さて、GitHubでは、レポジトリからページを作成する時に、内部でJekyllが使われます。 このとき、Jekyllやその他のgemのバージョンが、GitHubとローカルで違っていると、出力結果が異なる可能性があります。 GitHubで使うgemのバージョンは公開されています

これだけのgemについて人手でチェックするのは大変です。 それを解決するgemがgithub-pagesです。 このgemをGemfileに書いておけば、必要なgemを正しいバージョンで取り込んでくれるのです。

では、Gemfileを書き直してみましょう

source "https://rubygems.org"

gem "github-pages", "~> 227", group: :jekyll_plugins

gem "webrick"

バージョンの227は先程のページから取ってきます。 このバージョンは比較的頻繁に変わるので、書き換えが必要になることに注意しましょう。 このgemを書いておけば、jekyll-theme-leap-dayなどをGemfileに書く必要はありません。 github-pagesが関連gemを指定しているので、自動的にインストールされます。

Gemfileを更新したら、Gemfile.lockを削除して、bundle installします。

jekyll-github-metadataの警告メッセージ

Jekyllを動かしてみましょう。

$ bundle exec jekyll serve
Configuration file: /（クローンしたディレクトリ）/_config.yml
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
            Source: /（クローンしたディレクトリ）
       Destination: /（クローンしたディレクトリ）/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
                    done in 0.948 seconds.
 Auto-regeneration: enabled for '/（クローンしたディレクトリ）'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

下から5行目に警告メッセージが出ています。

GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.

はじめに「GitHub Metadata:」とあるので、jekyll-github-metadata gemの発出したメッセージであることがわかります。 このgemはgethub-pagesでインストールが指定されていたgemの1つです。 内容は、「GitHub APIの認証が見つかりませんでした。 一部のフィールドが欠落しているか、データが正しくない可能性があります。」ということですが、これだけでは何のことかわかりません。 jekyll-github-metadataのウェブサイトのAuthenticationページを見ると、次のようなことが書いてあります。

  • cname などの一部のフィールドでは、自分自身を認証する必要がある（このことの意味は私はよく分かっていませんが）。
  • それを解決するにはいくつかの方法がある
  • JEKYLL_GITHUB_TOKEN環境変数にPAT（以前https接続のために生成したパーソナル・アクセス・トークンのこと）をセットしてJekyllを起動する
  • netrc gemを用い、~/.netrcにユーザ名とPATを書く
  • OCTOKIT_ACCESS_TOKEN環境変数にPATをセットしてJekyllを起動する（1番目とほぼ同じ）

この3つのうちのどれかをすれば警告メッセージは無くなります。 （ただ、エラーが出ているわけではないので、無視してもそれほど大きな問題にはなりません）。 1番目と3番目の環境変数を使うのが簡単ですが、毎回これをするのは煩わしいです。 その点、2番めは一度セットすれば後は何もしなくて良いのが利点です。

今回はnetrcを使ってみます。 まず、~/.netrcがあるかどうかチェックします。 （~はユーザの（あなたの）ホームディレクトリです。ドットから始まるファイルは隠しファイルなので、CTRL+Hで表示できるようにして確認します）。 もしある場合は下記の内容を付け足します。 なければ新規にファイルを作り下記の内容で保存します。

machine api.github.com
    login ＜GitHubのユーザ名＞
    password ＜ＰＡＴ＞

次に、Gemfileにnetrc gemを加えます。

source "https://rubygems.org"

gem "github-pages", "~> 227", group: :jekyll_plugins

gem "webrick"
gem "netrc"

Gemfile.lockを削除し、bundle installします。 これでbundle exec jekyll serveで警告は出なくなったはずです。

GitHubと同じ表示になっていることを確認

表示された画面を見てみましょう。

以前と違うのは

  • メニューバーの「View on GitHub」がGitHubのレポジトリへのリンクになっている
  • 左下の方に「Project maintained by （ユーザ名）」の表示が現れている

ことです。 これらは、gethub-pages gemによってGItHubと同じ環境になったことの現れです。

以上で、ローカルでGitHubと同じ環境を構築できました。 前よりもより正確にテストをすることができます。

次回はウェブサイトにコンテンツを加える方法を見ていきます。