プラグイン

Jekyllはフックによるプラグイン(plugin)システムを備えており、これによりあなたのサイト向けに特化したコンテンツの生成が可能になります。Jekyllのソース自体を修正することなく、あなたのサイト用のコードを実行できます。

GitHub Pagesにおけるプラグイン

GitHub PagesはJekyllで動いていますが、ここで構築されるすべてのサイトは、セキュリティ上の理由から--safeオプションで生成され、カスタムプラグインが利用できないようになっています。残念ながら、これはあなたのプラグインをGitHub Pagesにデプロイしても動作しないことを意味します。

あなたのサイトを公開するためにGitHub Pagesを利用することはできますが、そのためには、Jekyllのソースファイルの代わりに、サイトをローカルで変換して、生成された静的ファイルをGitHubレポジトリにプッシュする必要があります。

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

プラグインをインストールする2つの方法があります。

  1. サイトのルートに_pluginsディレクトリを作って、プラグインをここに配置します。このディレクトリ内の*.rbで終わるすべてのファイルは、Jekyllがサイトを生成するときに読み込まれます。

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

     gems: [jekyll-test-plugin, jekyll-jsonify, jekyll-assets]
     # これで各gemが自動的に読み込まれます。
    
_pluginsgems は同時に使用できます。

前述した2つのプラグインの選択肢は、同じサイトにおいて同時に使うことができます。一方の使用は、他方の使用を制限しません。

通常、あなたが作るpluginは次の3つのカテゴリの何れかに該当します。

  1. ジェネレータ(Generators)
  2. コンバータ(Converters)
  3. タグ(Tags)

ジェネレータ(Generators)

独自ルールでJekyllに追加コンテンツを生成させる必要があるときは、ジェネレータを作ります。

ジェネレータは、generateメソッドを定義しているJekyll::Generatorのサブクラスであり、このメソッドは、Jekyll::Siteのインスタンスを取ります。

ジェネレータは、その副作用のために起動され、generateメソッドの返り値は無視されます。Jekyllは引き起こされる如何なる特定の副作用も期待しておらず、ただそのメソッドを呼ぶだけです。

ジェネレータは、Jekyllが存在するコンテンツの目録を作った後、サイトが生成される前に、動作します。YAML front-matterを備えたpageは、Jekyll::Pageのインスタンスとして格納され、site.pagesを通して利用可能になります。静的ファイルは、Jekyll::StaticFileのインスタンスになり、site.static_filesを通して利用可能になります。詳しくは、変数のページおよびJekyll::Siteを確認して下さい。

例えばジェネレータは、ビルド時に計算された値をテンプレート変数を使い挿入できます。次の例ではテンプレートreading.htmlは2つの変数、ongoingおよびdoneを持っており、これらはジェネレータにおいて値を埋め込まれます。

module Reading
  class Generator < Jekyll::Generator
    def generate(site)
      ongoing, done = Book.all.partition(&:ongoing?)

      reading = site.pages.detect {|page| page.name == 'reading.html'}
      reading.data['ongoing'] = ongoing
      reading.data['done'] = done
    end
  end
end

以下は、新しいページを生成する、より複雑なジェネレータです。

module Jekyll

  class CategoryPage < Page
    def initialize(site, base, dir, category)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'

      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
      self.data['category'] = category

      category_title_prefix = site.config['category_title_prefix'] || 'Category: '
      self.data['title'] = "#{category_title_prefix}#{category}"
    end
  end

  class CategoryPageGenerator < Generator
    safe true

    def generate(site)
      if site.layouts.key? 'category_index'
        dir = site.config['category_dir'] || 'categories'
        site.categories.keys.each do |category|
          site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
        end
      end
    end
  end

end

この例においてジェネレータは、各カテゴリごとにcategoriesディレクトリ下に一式のファイルを生成し、category_index.htmlレイアウトを使って、各カテゴリごとに記事をリスト表示します。

ジェネレータでは、1つのメソッドを実装すれば良いです。

メソッド 解説

generate

副作用でコンテンツを生成する

コンバータ(Converters)

サイトで利用したい新しいマークアップ言語があるときは、独自のコンバータを実装することで利用できるようになります。MarkdownおよびTextileマークアップ言語は、共にこの方法で実装されています。

YAML front-matterを忘れずに

Jekyllは先頭にYAMLヘッダーがあるファイルだけを変換しますが、これはたとえプラグインを使って追加されたコンバータであっても同じです。

以下は、.upcaseで終わる全postを対象に、これらをUpcaseConverterを使用して処理するコンバータの例です。

module Jekyll
  class UpcaseConverter < Converter
    safe true
    priority :low

    def matches(ext)
      ext =~ /^\.upcase$/i
    end

    def output_ext(ext)
      ".html"
    end

    def convert(content)
      content.upcase
    end
  end
end

コンバータには、最低3つのメソッドを実装する必要があります。

メソッド 解説

matches

与えられた拡張子はこのコンバータのアクセス可能な拡張子のリストにマッチするか?1引数を取る: ファイルの拡張子(ドットを含む)。マッチする場合はtrueを、それ以外はfalseを返す必要がある。

output_ext

出力ファイルに与えられる拡張子(ドットを含む)。 通常、これは".html"である。

convert

コンテンツの変換をするためのロジック。1引数を取る: ファイルの未加工のコンテンツ(YAML front matterを含まない)。文字列を返す必要がある。

この例で、UpcaseConverter#matchesは、ファイル名の拡張子が.upcaseであるかをチェックし、そうである場合、このコンバータを使ってレンダリングを行います。UpcaseConverter#convertは、このコンテンツを処理するために呼ばれます。この簡単なコンバータでは単に全コンテンツの文字列を大文字化します。そして、このpageを保存するときは.htmlの拡張子で保存します。

タグ(Tags)

サイトで専用Liquidタグを使いたいときは、タグシステムにフックさせることで実現できます。jekyllの組み込みサンプルには、’highlight’タグと’include’タグが含まれています。次の例は、pageが作られるときの時刻を出力する専用Liquidタグです。

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)

Liquidタグでは最低限、次を実装する必要があります。

メソッド 解説

render

タグのコンテンツを出力する。

また、Liquidテンプレートエンジンにこの専用タグを登録する必要があります。

Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)

上記の例で、任意のpageのどこにでも、次のようなタグを配置できるようになります。

<p>{% render_time page rendered at: %}</p>

これにより、page上に次のような出力が得られます。

<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

Liquidフィルタ(Liquid filters)

上でタグを追加したように、Liquidテンプレートシステムに独自フィルタを追加することもできます。フィルタは、Liquidにメソッドをエクスポートする簡単なモジュールです。すべてのメソッドは、フィルタの入力としての少なくとも1つの引数を取る必要があります。その返り値はフィルタの出力になります。

module Jekyll
  module AssetFilter
    def asset_url(input)
      "http://www.example.com/#{input}?#{Time.now.to_i}"
    end
  end
end

Liquid::Template.register_filter(Jekyll::AssetFilter)
ProTip™: Liquidを通じたsiteオブジェクトへのアクセス

Jekyllではsiteオブジェクトにアクセスでき、これはLiquidのcontext.registers機能を通じたcontext.registers[:site]により可能になります。例えば、グローバル設定ファイル_config.ymlcontext.registers[:site].configを使ってアクセスできます。

フラグ(Flags)

プラグインを書くときに注意すべき2つのフラグがあります。

フラグ 解説

safe

任意のコードの実行が許可されていない環境で、対象のプラグインが安全に実行されるものであるか否かをJekyllに伝えるブーリアンフラグ。これはGitHub Pagesで利用され、そこでどのコアプラグインが利用でき、またどのプラグインが起動上安全でないかが判断される。あなたのプラグインが任意コードの実行を許可しない場合には、trueをセットする。これをセットしたとしてもGitHub Pagesは依然としてあなたのプラグインを読み込むようにはならないが、Jekyll本体に組み込むべくプラグインを供するつもりなら、このオプションを正しく設定しておくのがよい。

priority

このフラグは、プラグインがロードされる順番を決定する。有効な値は、 :lowest, :low, :normal, :high, および :highest。最上位(highest priority)のものは最初に適用され、最下位(lowest priority)のものは最後に適用される。

上で説明したサンプルプラグインの一つを使う場合、これら2つのフラグの指定は次のようになります。

module Jekyll
  class UpcaseConverter < Converter
    safe true
    priority :low
    ...
  end
end

利用可能なプラグイン

幾つかの便利なプラグインが次の場所にあります。

ジェネレータ

コンバータ

フィルタ

  • Truncate HTML by Matt Hall: マークアップ構造を維持しつつHTMLをトランケートするJekyllフィルタ。
  • Domain Name Filter by Lawrence Woodman: ドメイン名が残るように入力テキストをフィルタする。
  • Summarize Filter by Mathieu Arnold: <div id="extended">タグの後のマークアップを除去する。
  • URL encoding by James An: URIパーセントエンコーディング。
  • JSON Filter by joelverhagen: 入力テキストを得てJSONとして出力するフィルタ。JavaScriptをレンダリングするのに好適。
  • i18n_filter: I18nローカライゼーションに使うLiquidフィルタ。
  • Smilify by SaswatPadhi: コンテンツ内の顔文字テキスト(emoticons)をテーマ別顔文字画像に変換する。
  • Read in X Minutes by zachleat: 文字列(ブログ記事のコンテンツ)のリーディング時間を見積る。
  • Jekyll-timeago: 時間値を時間経過の単語に変換する。
  • pluralize: 数字と単語を文法的に正しい量(例:“1 minute” or “2 minutes”)で簡単に結合する。
  • reading_time: 単語をカウントし、テキスト片のリーディング時間を見積る。この場合、対象テキストとして含めるにそぐわないHTML要素は無視される。
  • Table of Content Generator: 目次(TOC)を含むHTMLコードを生成する。目次は多様な方法でカスタマイズ可能であり、例えば、目次を持たないページを指定できる。
  • jekyll-humanize: これはDjangoアプリhumanizeの移植版で、データに”人間らしさ”を追加する。各メソッドは、Fluidタイプフィルタを表し、Jekyllサイトのテンプレートで利用可能。Jekyllは静的サイトを生成するので、いくつかのオリジナルメソッドは移植版において論理的な意味をなさない(例:naturaltime)。
  • Jekyll-Ordinal: “st”、”nd”、”rd”、”th”などの日付けの序数を出力するJekyllのLiquidフィルタ。
  • Deprecated articles keeper by Kazuya Kobayashi: 記事の古さを監視するシンプルなJekyllフィルタ。

タグ

コレクション

  • Jekyll Plugins by Recursive Design: GitHubのREADMEからプロジェクトページを生成するプラグイン、カテゴリページとサイトマップのジェネレータ。
  • Company website and blog plugins by Flatterline, a Ruby on Rails development company: ポートフォリオ/プロジェクトページのジェネレータ、チーム/個人ページのジェネレータ、postで使える著者略歴用のLiquidタグ、およびその他の小さなプラグイン群。
  • Jekyll plugins by Aucor: 不要な改行/空白を除去するプラグインと、weight属性でページをソートするプラグイン。

その他

  • Pygments Cache Path by Raimonds Simanovskis: Pygmentsでシンタックスハイライトされたコードをキャッシュするプラグイン。
  • Draft/Publish Plugin by Michael Ivey: ドラフトとしてpostを保存する。
  • Growl Notification Generator by Tate Johnson: GrowlにJekyllの通知を送る。
  • Growl Notification Hook by Tate Johnson: 上記の高機能な他の選択肢だが、Jekyllの“hook”のフォーク版が必要。
  • Related Posts by Lawrence Woodman: site.related_postsを上書きし、関係性を評価したカテゴリを使えるようにする。
  • Tiered Archives by Eli Naeher: 多段テンプレート変数を生成し、年および月ごとにアーカイブをグループ化できるようにする。
  • Jekyll-localization: レンダリングエンジンにローカライゼーション機能を追加するJekyllプラグイン。
  • Jekyll-rendering: レンダリングエンジンの他の選択肢を提供するJekyllプラグイン。
  • Jekyll-pagination: ページネーションジェネレータを拡張するJekyllプラグイン。
  • Jekyll-tagging: タグクラウドおよびタグページを自動で生成するJekyllプラグイン。
  • Jekyll-scholar: 学術研究向けブログのためのJekyll拡張。
  • Jekyll-asset_bundler: JavaScriptとCSSをバンドルしミニファイする。
  • Jekyll-assets by ixti: Rails風アセットパイプライン(アセットをCoffeeScript, Sass, LESSなどで書いて、アセット内の簡単な宣言的コメントで自動バンドリングのための依存関係を指定し、ミニファイおよび圧縮を実行し、JSTテンプレートを使用し、キャッシュ消去(cache bust)をし、その他諸々をする)。
  • JAPR: Jekyll Asset Pipeline Reborn - JavaScriptおよびCSSファイル群を収集、変換および圧縮するJekyll用の強力なアセットパイプライン。
  • File compressor by mytharcher: サイトのビルドにおいてHTMLおよびJavaScriptファイルを圧縮する。
  • Jekyll-minibundle: アセットのバンドリングおよびキャッシュ消去(cache busting)を、指定の外部ミニファイツールを使って行う。他のGemに依存しない。
  • Singlepage-jekyll by JCB-K: Jekyllを動的な単一ページWebサイトに変える。
  • generator-jekyllrb: JekyllをYeomanでラップするジェネレータ。Yeomanは、最新のWebアプリを構築するためのツールセットおよびワークフローである。
  • grunt-jekyll: 文字通りのJekyll用Gruntプラグイン。
  • jekyll-postfiles: _postfilesディレクトリと{{ postfile }}タグを追加し、postから参照するファイルを常にpostのすぐそばに置けるようにする。
  • A layout that compresses HTML by Anatol Broder: サイト生成時に作動するHTML圧縮用プラグイン。GitHub Pages対応。圧縮方法は設定可能。
  • Jekyll CO₂: ハワイ州マウナロア観測所における大気中CO₂の月ごとの変化を表示するHTMLを生成する。

エディタ

  • sublime-jekyll: Jekyll静的サイトのためのSublimeテキストエディタパッケージ。本パッケージは、Jekyllサイトの生成を助け投稿を容易にするもので、これは、キーテンプレートタグおよびフィルタ、並びに、良く使う補完および現在のdate/datetimeコマンド(postの日付け決め用)へのアクセスを提供することで実現される。本パッケージは手作業でGitHubから、またはPackage Controlを通してインストールできる。
  • vim-jekyll: Vimから離れることなく新規投稿およびjekyll buildの起動を可能にするVimプラグイン。
Jekyllプラグイン求む

このリストに追加したいJekyllプラグインがある場合は、貢献(contributing)ページを読んで、そうする方法を調べてください。