T.I.D.

Git や GitHub と戯れる、オレオレ的おとなの遊び場

Jekyllの実験的テンプレート

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

トップページでの表示記事数と、先頭記事以外のカラム数。

date_format

使える書式は、Module: Liquid::StandardFilters — Documentation for liquid (2.2.2) （GitHub の Liquid バージョンと同じ） を参考に。

truncate_len

トップページで紹介する記事の表示文字数。

次のように {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) で表示する、サムネイル画像。

comments

3rd パーティー製コメントシステムを有効にする。

published

true で記事公開、false で保留。

category

カテゴリは、配列 [...] を使って複数指定可。この場合、左から順に親子関係となる。

tags

タグも配列を使用可能。カテゴリとは異なり、親子関係はない。

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

Comments