jekyll で本格的ブログを作るためのテンプレート jekyll-experiment を作ってみたが、色々と作り込むうちに複雑になってきたので、ここに記録しておく。
制作方針
- モジュール化により、カスタマイズし易くすること。
- ブログに必要な最小限の機能が、プラグインの使えない GitHub Pages 上の jekyll でも動作すること。
構成
.
├── _deploy/ # デプロイ時の静的ファイル群を保存しておく
├── _includes/ # 他からインクルードされるテンプレート部品
│ ├── asides/ # サイドバー用各種テンプレート部品
│ ├── post/ # 個別記事ページ用各種テンプレート部品
│ ├── libs/ # 小さなテンプレート部品
│ ├── js/ # 小さな js 部品
│ ├── css/ # 小さな css 部品
│ │ └── pygments/ # pygments 用 css
│ └── bootstrap-2.1.1/ # bootstrap の部品
├── _layouts/ # ページ用テンプレート
├── _plugins/ # 拡張用プラグイン（参考用）
├── _posts/ # 記事
├── _site/ # ここに一時的な静的ファイル群が作られる
├── assets/ # サイト用リソース
│ ├── bootstrap-2.1.1/ # 必要な bootstrap 部品をインクルードする
│ ├── css/ # 必要な css 部品をインクルードする
│ ├── js/ # 必要な js 部品をインクルードする
│ ├── ico/ # ファビコンなど
│ └── img/ # サイト用画像
├── blog/ # ブログ用テンプレート
└── project/ # プロジェクト用テンプレート
1. _config.yml の設定
url、baseurl
GitHub プロジェクトページの場合は、次のように指定する。
url: http://USERNAME.github.com/REPOSITORY
baseurl: /REPOSITORY
paginate、columns
トップページでの表示記事数と、先頭記事以外のカラム数。
使える書式は、Module: Liquid::StandardFilters — Documentation for liquid (2.2.2) （GitHub の Liquid バージョンと同じ） を参考に。
truncate_len
トップページで紹介する記事の表示文字数。
navbar_list
次のように {name, link} のペアでナビゲーションバーのメニューを定義。
navbar_list:
- name: Blog
link: /
- name: Project
link: /project/
- name: About
link: /about.html
サブメニューは、dropdown: &dropdown を使い、次のように定義。
navbar_list:
- name: Blog
link: /
dropdown: &dropdown
- name: Categories
link: /blog/categories.html
- name: Tags
link: /blog/tags.html
これ以上の多階層化は、_includes/navbar.html に直接マークアップするのが吉。
またリンク部をハイライトするためには、テンプレート側の YAML ディレクティブ group に、親メニューの name を指定する。以下は、/blog/categories.html の例。
---
layout: default
title: Archives
group: Blog
---
pygments_style
Pygments - Python syntax highlighter の Online demo で、カラーリングを確認するのが吉。
カラーリングに関しては、次のサイトもご参考。
2. 記事の YAML ディレクティブ
excerpt
トップページ (index.html) で表示する、記事の要旨。
thumbnail
トップページ (index.html) で表示する、サムネイル画像。
3rd パーティー製コメントシステムを有効にする。
published
true で記事公開、false で保留。
category
カテゴリは、配列 [...] を使って複数指定可。この場合、左から順に親子関係となる。
タグも配列を使用可能。カテゴリとは異なり、親子関係はない。
3.「続きを読む」機能
トップページ (index.html) の表示時、_includes/libs/truncate_xxxx で以下の処理を実行する。
3.1 excerpt の処理
記事の YAML ディレクティブにコレがあれば、要旨として表示する。
3.2 <!--more--> の処理
safe: false な jekyll 環境では、_plugins/postmore.rb を使って <!--more--> で分割した文字列の前半をレンダリングする。一方プラグインが使えない GitHub ページ上の jekyll では、次のように Liquid で、<!--more--> から記事の終わりまでコメント化し、擬似的な more 機能を実現する。
{% if post.content contains '<!--more-->' %}
{{ post.content | remove:'-->' }}-->
{% endif %}
テキストとしては送られるが、高々数十キロバイトだろうから、目をつぶってもらうというわけである。
余談だが、次のような Liquid コードも試してみた。が、適当な1バイトの区切り文字 SEP をセットできないのでダメ。何か良い案はないだろうか？
{{ post.content | replace_first:'<!--more-->', SEP | split:SEP | first }}
参考情報
3.3 先頭から既定文字数だけを表示する処理
excerpt および <!--more--> が共にない場合、先頭の truncate_len だけ文字を表示する。GitHub 上の jekyll （バージョン 2.2.2） の場合、truncate フィルタがユニコードに対応しておらず、単なるバイト数でカウントされてしまうため、日本語が文字化けする可能性がある。そこでかなりトリッキーな方法ではあるが、末尾の文字コードを調べ、適切な所で丸める処理を Liquid で実装した。
4. カテゴリ、タグ
Template Data - mojombo/jekyll Wiki にある通り、テンプレートからは site.categories （ハッシュ） や page.categories （配列） などでアクセスすることが出来る。_includes/libs/list_categories と _includes/libs/list_tags にそれらの扱いを集約すると共に、両者をフラグで使い分ける仕様とした。
またカテゴリは、親子関係を表す配列で提供されるのが jekyll の仕様である。例えば、_post/1970-1-1-hello-world.md の YAML ディレクティブに次のようなカテゴリが指定されていたとする。
title: "hello world!"
category: [parent, child]
もし、_config.yml のパーマリンク設定が permalink: /blog/:categories/:title.html であった場合、上記の記事は、次のように展開される。
/blog/parent/child/hello-world.html
5. bootstrap 関連
コレのコンフィグレーションを色々できるようにしたことが複雑化の原因。不要なら一切を削除するのがお勧め。
5.1 基本構成
assets/bootstrap-X.Y.Z/ 下のファイルが、_includes/bootstrap-X.Y.Z/ 下の部品をインクルードする構成とした。
例えば、assets/bootstrap-2.1.1/js/bootstrap.custom.js は、次のように bootstrap の js 部品をインクルードする。
---
---
{% include bootstrap-2.1.1/js/bootstrap-carousel.js %}
{% include bootstrap-2.1.1/js/bootstrap-collapse.js %}
{% include bootstrap-2.1.1/js/bootstrap-dropdown.js %}
{% include bootstrap-2.1.1/js/bootstrap-tab.js %}
{% include bootstrap-2.1.1/js/bootstrap-transition.js %}
コレのポイントは、YAML ディレクティブが空でも jekyll がちゃんと処理してくれて、自分自身のファイル形式に変換してくれること。
css ファイルは、web-based Customizer から適当なモジュールを選択し、ダウンロードしたファイルで代用している。そのうち LESS をインストールし、モジュール化したい。
5.2 _config.yml の設定。
bootstrap
custom を指定すると /assets/bootstrap-X.Y.Z/ のカスタムファイルを用いる。この場合、_includes/bootstrap-X.Y.Z/ から必要な部品をインクルードする。original あるいはそれ以外では、BootstrapCDN にアップされているファイルを使う。
bootstrap_ver
バージョン X.Y.Z を指定。
bootswatch_ver
テーマファイルのバージョンを指定。
responsive_bp
ナビゲーションバーを折り畳みタイプにする、メディアクエリ上のブレーク・ポイント。assets/bootstrap-X.Y.Z/bootstrap-responsive.custom.css に、この値をレンダリングする。
jquery_ver
本当は 1.8.x を使いたいんだけれど、私のスマホ （Optimus L-01D/Android 2.3） のネイティブなブラウザが落ちる。Firefox なら大丈夫。たぶんブラウザのバグ （だと思う）。
参考情報
6. Rakefile のエントリー
preview
rake preview もしくは rake で http://localhost:4000/ でのテストが可能。
post
新規投稿。次の書式が可能。
rake post title="title of my article"
rake post["title of my article"]
page
新規ページの作成。
rake page name="about.html"
setup_remote
記事の公開に git push を使う場合の、リモートの設定。push するリモート側のブランチは、Rakefile 中のグローバルなハッシュ CONFIG['deploy_branch'] で指定する。
deploy
setup_remote で設定したリモートサーバに記事を git push する。_site に出来た静的ファイルは、プレビュー中にも変わってしまうため、_deploy ディレクトリにコピーし、デプロイ用ファイルを確定させる。
7. Gemfile 関連
gem 'jekyll'
RubyGems に現在公開されている jekyll は pygmentize ごとにプロセスを起動するため、処理時間がかかるとのこと （情報源：pygmentsが原因でjekyllが重くなってた - hokaccha.hamalog v2）。GitHub 上の最新バージョンを使う方が吉かも。
gem 'gsl'
jekyll のソースを読む限り、lsi: false を指定すると、単に最新の記事数件を 「関連する記事」 とするだけである。lsi: true だと、少しはマシになるらしいが、処理時間がかかる模様。gsl を使えば、10倍高速化できるとのこと （未確認）。
gem 'rake'
いつの間にか、システムにインストールしたバージョンを 0.9.2.2 に上げてしまったようで、Octopress が指定しているバージョン 0.9.2 と競合するようになった。Octopress 側を bundle exec rake ... で対応しているが、そもそも各アプリごとに gem を分けた方が良いかもしれない。
bundler の参考サイト
8. その他、テンプレート作成で参考になったサイト
jekyll、Liquid の解説
Bootstrap
]]>
、プロジェクトが完成してお祝いしたいときには、「:beer:」で 
となるわけ。
