自分のサイト用コンテンツを生成するのに、Jekyllはフックによるプラグインシステムを備えています。プラグインを作成することにより機能を追加することができるわけです。そのプラグイン作成の基本を概観しますがJekyll プラグインを参考にさせていただきました。
Jekyll の 主なプラグインは次の３種類になります(Jekyll のバージョン2.5.0からJekyll 実行時のサブコマンドをプラグインにて作成してJekyll を拡張できるCommandsというプラグインが使えますが、現時点でCommandsに関する説明はしておりません。興味があるようでしたらJekyll Plugins を参照してください)。
主な３種類のプラグイン
| プラグイン名 | 解説 |
|---|---|
| ジェネレータ(Generators) | Jekyllに追加コンテンツを生成させる |
| コンバータ(Converters) | 指定した(例えば、拡張子が.convertである)ファイルに対してコンテキストに変更を加えてから出力する |
| タグ(Tags) | 独自のLiquidタグを定義する |
プラグインのインストール
ディレクトリ_pluginsに「.rb」ファイルを置くことで自作のプラグインを追加できます。
_pluginsディレクトリ内の「*.rb」ファイルは、Jekyllがサイトを生成するときに読み込まれます。
_config.ymlファイルに、gemsをキーとし、使いたいプラグインのgem名を値とする行を記述します。
例：
1
gems: [プラグイン名, 別のプラグイン名]
あるいはGemfileに使いたいプラグインのgem名を記述します(Commandsプラグインではこの方法でプラグインを使えるようにします)。
例：
1 2 3
group :jekyll_plugins do gem "my-jekyll-plugin" end
以下で、各プラグインの作成で必要最小限の構成を見ていきます。プラグインファイルに記述する内容の雛形になります。
プラグインの作成
プラグインを書くときに指定できるフラグが２つあります。
| フラグ | 解説 |
|---|---|
| safe | 任意のコードの実行が許可されていない環境で、対象のプラグインが安全に実行されるものであるか否かをJekyllに伝えるブーリアンフラグ。あなたのプラグインが任意コードの実行を許可しない場合には、trueをセットする。Jekyll本体に組み込むべくプラグインを提供するつもりなら、このオプションを正しく設定しておくのがよいでしょう。 |
| priority | このフラグは、プラグインがロードされる順番を決定する。有効な値は、 :lowest, :low, :normal, :high, および :highest。最上位(highest priority)のものは最初に適用され、最下位(lowest priority)のものは最後に適用されます。 |
ジェネレータ(Generators)
(静的ページに埋め込まれた)テンプレート変数に値を埋め込んだり、新しいページを生成することができます。
1
2
3
4
5
6
7
8
9
10
module Jekyll
class NewPluginGenerator < Generator
safe true
def generate(site)
...
end
end
end
クラスの継承元
Jekyll::Generator必要なメソッド
メソッド 解説 generate 副作用でコンテンツを生成する 簡単な具体例
記事(site.postsのリストにPostオブジェクトとして格納されている)ごとに、異なる値を記事内に表示させたい時(例えば「パンくずリスト」を表示させたい、ページネーションの仕方をカスタマイズしたいなど)には、この「ジェネレータ」プラグインで実現することができます。すなわち、Postオブジェクトごとに表示させたい値をセットし、表示させたい場所でその値を取り出すわけです。
File: _plugins/generator_example.rb
1
2
3
4
5
6
7
8
9
10
11
module Jekyll
class GeneratorExample < Generator
def generate(site)
site.posts.each do |post|
...
post.data["aaa"] = "<div>ポストごとに異なる値</div>"
...
end
end
end
end
6行目でポストごとに表示させたい値をdataハッシュにaaaというキーでセットしました。
その値を表示させたいところにJekyll変数pageを使って出力します。
File: post.html
1
2
3
...
{{ page.aaa }}
...
post.dataハッシュのキーがpageのプロパティとして値を受け取れることに注意してください。
コンバータ(Converters)
指定した拡張子を持つファイルのコンテンツを変換してファイルを生成することができる。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
module Jekyll
class NewPluginConverter < Converter
safe true
priority :low
def matches(ext)
ext =~ /^\.convert$/i
end
def output_ext(ext)
".html"
end
def convert(content)
...
end
end
end
クラスの継承元
Jekyll::Converter必要なメソッド
メソッド 解説 matches 与えられた拡張子はこのコンバータのアクセス可能な拡張子のリストにマッチするか？１引数を取る: ファイルの拡張子(ドットを含む)。マッチする場合はtrueを、それ以外はfalseを返す必要がある。 output_ext 出力ファイルに与えられる拡張子(ドットを含む)。 通常、これは”.html”である。 convert コンテンツの変換をするためのロジック。１引数を取る: ファイルの未加工のコンテンツ(YAML front matterを含まない)。文字列を返す必要がある。
Liquidタグ
任意のページにタグ(下の例では {% render_new_plugin %})を書き入れることでその場所にプラグインの出力を埋め込むことができます。
1
2
3
4
5
6
7
8
9
module Jekyll
class NewPluginTag < Liquid::Tag
def render(context)
...
end
end
end
Liquid::Template.register_tag('render_new_plugin', Jekyll::NewPluginTag)
クラスの継承元
Jekyll::Liquid::Tag必要なメソッド
メソッド 解説 render タグのコンテンツを出力する タグの登録
Liquid::Template.register_tag(‘タグ名’, Jekyll::クラス名)
簡単な具体例
次の例は、pageが作られたときの時刻を出力する専用Liquidタグです。
File:_plugins/render_time_tag.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
module Jekyll
class RenderTimeTag < Liquid::Tag
def initialize(tag_name, text, tokens)
super
@text = text
end
def render(context)
"#{@text} #{Time.now}"
end
end
end
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
どのページにでもタグを次のように記述することができます。
1
<p>{% render_time 更新日時：%}</p>
その結果、ページには次のように出力されます。
1
<p>更新日時： 2015-05-22 12:51:15 +0900</p>