Posts Jekyll - Pluginを作る
Post
Cancel

Jekyll - Pluginを作る

自分のサイト用コンテンツを生成するのに、Jekyllはフックによるプラグインシステムを備えています。プラグインを作成することにより機能を追加することができるわけです。そのプラグイン作成の基本を概観しますがJekyll プラグインを参考にさせていただきました。

Jekyll の 主なプラグインは次の3種類になります(Jekyll のバージョン2.5.0からJekyll 実行時のサブコマンドをプラグインにて作成してJekyll を拡張できるCommandsというプラグインが使えますが、現時点でCommandsに関する説明はしておりません。興味があるようでしたらJekyll Plugins を参照してください)。

主な3種類のプラグイン

プラグイン名解説
ジェネレータ(Generators)Jekyllに追加コンテンツを生成させる
コンバータ(Converters)指定した(例えば、拡張子が.convertである)ファイルに対してコンテキストに変更を加えてから出力する
タグ(Tags)独自のLiquidタグを定義する

プラグインのインストール

  1. ディレクトリ_pluginsに「.rb」ファイルを置くことで自作のプラグインを追加できます。

    _pluginsディレクトリ内の「*.rb」ファイルは、Jekyllがサイトを生成するときに読み込まれます。

  2. _config.ymlファイルに、gemsをキーとし、使いたいプラグインのgem名を値とする行を記述します。

    例:

1
gems: [プラグイン名, 別のプラグイン名]
  1. あるいはGemfileに使いたいプラグインのgem名を記述します(Commandsプラグインではこの方法でプラグインを使えるようにします)。

    例:

    1
    2
    3
    
    group :jekyll_plugins do
      gem "my-jekyll-plugin"
    end
    

以下で、各プラグインの作成で必要最小限の構成を見ていきます。プラグインファイルに記述する内容の雛形になります。

プラグインの作成

プラグインを書くときに指定できるフラグが2つあります。

フラグ解説
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
  1. クラスの継承元

    Jekyll::Generator

  2. 必要なメソッド

    メソッド解説
    generate副作用でコンテンツを生成する
  3. 簡単な具体例

記事(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
  1. クラスの継承元

    Jekyll::Converter

  2. 必要なメソッド

    メソッド解説
    matches与えられた拡張子はこのコンバータのアクセス可能な拡張子のリストにマッチするか?1引数を取る: ファイルの拡張子(ドットを含む)。マッチする場合はtrueを、それ以外はfalseを返す必要がある。
    output_ext出力ファイルに与えられる拡張子(ドットを含む)。 通常、これは”.html”である。
    convertコンテンツの変換をするためのロジック。1引数を取る: ファイルの未加工のコンテンツ(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)
  1. クラスの継承元

    Jekyll::Liquid::Tag

  2. 必要なメソッド

    メソッド解説
    renderタグのコンテンツを出力する
  3. タグの登録

    Liquid::Template.register_tag(‘タグ名’, Jekyll::クラス名)

  4. 簡単な具体例

    次の例は、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>
シェア
#内容発言者

WPScanでWordPressサイトをチェックする

RailsでAjax処理を実装