Translation of Jekyll Plugins

Plugins.textile

https://github.com/mojombo/jekyll/wiki/Plugins

Jekyllプラグインシステムのフックは、あなたのサイト向けに特化したコンテンツの生成を可能にします。Jekyllのソースを修正することなく、あなたのサイト用のコードを実行できます。

The Jekyll plugin system hooks allow you to create custom generated content specific to your site. You can run custom code for your site without having to modify the Jekyll source itself.

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

h2. Installing a plugin

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

In your site source root, make a _plugins directory. Place your plugins here. Any file ending in *.rb inside this directory will be required when Jekyll generates your site.

通常、作られるpluginは次の３つのカテゴリの何れかに該当します。

1. ジェネレータ
2. コンバータ
3. タグ

In general, plugins you make will fall into one of three categories:

1. Generators
2. Converters
3. Tags

ジェネレータ

h2. Generators

独自ルールでJekellに追加コンテンツを生成させる必要があるときは、ジェネレータを作ります。例えば、次のようなものになります。

You can create a generator when you need Jekyll to create additional content based on your own rules. For example, a generator might look like this:

module Jekyll

  class CategoryIndex < 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 CategoryGenerator < Generator
    safe true
    
    def generate(site)
      if site.layouts.key? 'category_index'
        dir = site.config['category_dir'] || 'categories'
        site.categories.keys.each do |category|
          write_category_index(site, File.join(dir, category), category)
        end
      end
    end
  
    def write_category_index(site, dir, category)
      index = CategoryIndex.new(site, site.source, dir, category)
      index.render(site.layouts, site.site_payload)
      index.write(site.dest)
      site.pages << index
    end
  end

end

この例で、ジェネレータは`category_index.html`レイアウトを使って、`categories`ディレクトリ以下に、各カテゴリ内の投稿をリストアップする一連のカテゴリ別ファイルを作ります。

In this example, our generator will create a series of files under the `categories` directory for each category, listing the posts in each category using the `category_index.html` layout.

ジェネレータでは、次の１メソッドの実装が必要です。

1. generate: 生成されるコンテンツの文字を出力

Generators are only required to implement one method:

1. generate: string output of the content being generated

コンバータ

h2. Converters

サイトで利用したい新しいマークアップ言語があるときは、独自のコンバータを実装することで利用できるようになります。MarkdownおよびTexttileマークアップ言語は、共にこの方法で実装されています。 JekyllはYAMLヘッダーを持ったファイルだけを変換する、ということを覚えておいてください。 ファイルの先頭にYAMLヘッダーがなければ、Jekyllはそのファイルを無視し、コンバータには送りません。

If you have a new markup language you’d like to include in your site, you can include it by implementing your own converter. Both the markdown and textile markup languages are implemented using this method. Please note that Jekyll will only convert files that also have a YAML header at the top. If there is no YAML header at the top of the file, Jekyll will ignore it and not send it through the converter.

次の例は、.upcaseで終わるすべての投稿に対し、UpcaseConverterを使って処理を実行するコンバータです。

Below is a converter that will take all posts ending in .upcase and process them using the 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

コンバータでは少なくとも次の３つのメソッドの実装が必要です。

1. matches: ページで実行される特定のコンバータを決めるために呼ばれる。
2. output_ext: 出力ファイルの拡張子。通常は".html"。
3. convert: コンテンツの変換をするためのロジック。

Converters should implement at a minimum 3 methods:

1. matches: Called to determine whether the specific converter will run on the page.
2. output_ext: The extension of the outputted file, usually “.html”
3. convert: Logic to do the content conversion

この例で、UpcaseConverter#matchesメソッドは、ファイルの終わりが’upcase’で終わっているかチェックし、そうである場合、このコンバータを使ってレンダリングを行います。つまり、UpcaseConverter#convertメソッドを呼んで、コンテンツを処理（この簡単なコンバータでは単にコンテンツの全文字列をキャピタライズ）します。そして、このページを保存するときは.html拡張子で保存します。

In our example, UpcaseConverter#matches checks if our filename ends in the word ‘upcase’, and will render using the converter if it does. It will call UpcaseConverter#convert to process the content – in our simple converter we’re simply capitalizing the entire content string. Finally, when it saves the page, it will do so with the .html extension.

タグ

h2. Tags

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

If you’d like to include custom liquid tags in your site, you can do so by hooking into the tagging system. Built-in examples from jekyll include the ‘highlight’ and the ‘include’ tag.

例として、そのページが作られるときの時間を出力する専用liquidタグを示します。

As an example, here is a custom liquid tag that will output the time the page was rendered:

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タグでは最低限、次を実装する必要があります。

1. render: タグの内容を出力する

At a minimum, liquid tags must implement:

1. render: Outputs the content of the tag

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

You must also register the custom liquid tag with the Liquid templating system by calling:

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

上の例で、ページのどこにでも、次のようなタグを配置できるようになります。

In the example above, we can place the following tag anywhere in one of our pages:

{% render_time page rendered at: %}

これによりページ上に次のような出力が得られます。

And we would get something like this on the page:

page rendered at: Tue June 22 23:38:47 -0500 2010

liquidフィルタ

h2. Liquid filters

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

You can add your own filters to the liquid system much like you can add tags above. Filters are simply modules that export their methods to liquid. All methods will have to take at least one parameter which represents the input of the filter. The return value will be the output of the filter.

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)

上級者向け: liquidの@context.registers featureを通してsiteオブジェクトにアクセスできます。Registerは、任意のコンテキストのオブジェクトを持てるハッシュです。Jekyllでは、registerを通してsiteオブジェクトにアクセスできます。例えば、次のようにグローバル設定(_config.yml)にアクセスできます。@context.registers[:site].config['cdn']

Advanced: you can access the site object through the @context.registers feature of liquid. Registers a hash where arbitrary context objects can be attached to. In Jekyll you can access the site object through registers. As an example, you can access the global configuration (_config.yml) like this: @context.registers[:site].config['cdn'].

フラグ

h3. Flags

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

1. safe: Github Pagesで使用されることの除外の目的で、プラグインが安全にJekyllコアに含まれるようにするブーリアン。通常はtrueをセットする。

2. priority: プラグインがロードされる順番を決定する。有効な値は、:lowest, :low, :normal, :high, :highest

There are two flags to be aware of when writing a plugin:

1. safe: boolean that allows a plugin to be safely included in jekyll core for exclusion from use with GitHub pages. In general, set this to true.
bq. 2. priority: determines what order the plugin is loaded in. Valid values are: :lowest, :low, :normal, :high, :highest

利用可能なプラグイン

h2. Available Plugins

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

There are a few useful, prebuilt plugins at the following locations:

1. Truncate HTML while preserving markup structure by Matt Hall
2. Generic Blog Plugins by Jose Diaz-Gonzalez : Contains plugins for tags, categories, archives, as well as a few liquid extensions
3. Domain Name Filter by Lawrence Woodman : Filters the input text so that just the domain name is left
4. Jekyll Plugins by Recursive Design : Plugin to generate Project pages from github readmes, a Category page plugin, and a Sitemap generator
5. Tag Cloud Plugin from a Jekyll walk-through : Plugin to generate a Tag Cloud
6. Pygments Cache Path by Raimonds Simanovskis : Plugin to cache syntax-highlighted code from Pygments
7. Delicious Plugin by Christian Hellsten : Fetches and renders bookmarks from delicious.com.
8. Ultraviolet plugin by Steve Alex : Jekyll Plugin for Ultraviolet
9. HAML plugin by Sam Z : HAML plugin for jekyll
10. ArchiveGenerator by Ilkka Laukkanen : Uses this archive page to generate archives
11. Tag Cloud Plugin by Ilkka Laukkanen : Jekyll tag cloud / tag pages plugin
12. HAML/SASS Converter by Adam Pearson : Simple haml-sass conversion for jekyll. Fork by Sam X
13. SASS scss Converter by Mark Wolfe : Jekyll Converter which uses the new css compatible syntax, based on the one written by Sam X.
14. GIT Tag by Alexandre Girard : Jekyll plugin to add Git activity inside a list
15. Draft/Publish Plugin by Michael Ivey
16. Less.js generator by Andy Fowler : Jekyll plugin to render less.js files during generation.
17. Less Converter by Jason Graham : A Jekyll plugin to convert a .less file to .css
18. Less Converter by Josh Brown
19. MathJax Liquid Tags by Jessy Cowan-Sharp : A simple liquid tag for Jekyll that converts {% m } and { em } into inline math, and { math } and { endmath %} into block equations, by replacing with the appropriate MathJax script tags.
20. Non-JS Gist Tag by Brandon Tilley A Liquid tag for Jekyll sites that allows embedding Gists and showing code for non-JavaScript enabled browsers and readers.
21. Growl Notification Generator by Tate Johnson
22. Growl Notification Hook by Tate Johnson : Better alternative to the above, but requires his “hook” fork.
23. Version Reporter by Blake Smith
24. Upcase Converter by Blake Smith
25. Render Time Tag by Blake Smith
26. Summarize Filter by Mathieu Arnold
27. Status.net/OStatus Tag by phaer
28. CoffeeScript converter by phaer : Put this file in _plugins/ and write a YAML header to your .coffee files (i.e. “-\n—-\n”). See http://coffeescript.org for more info
29. Raw Tag by phaer. : Keeps liquid from parsing text betweeen {% raw } and { endraw %}
30. URL encoding by James An
31. Sitemap.xml Generator by Michael Levin
32. Markdown references by Olov Lassus : Keep all your markdown reference-style link definitions in one file (_references.md)
33. Full-text search by Pascal Widdershoven : Add full-text search to your Jekyll site with this plugin and a bit of JavaScript.
34. Stylus Converter Convert .styl to .css.
35. Embed.ly client by Robert Böhnke Autogenerate embeds from URLs using oEmbed.
36. Logarithmic Tag Cloud : Flexible. Logarithmic distribution. Usage eg: {% tag_cloud font-size: 50 – 150%, threshold: 2 %}. Documentation inline.
37. Related Posts by Lawrence Woodman : Overrides site.related_posts to use categories to assess relationship
38. AliasGenerator by Thomas Mango : Generates redirect pages for posts when an alias configuration is specified in the YAML Front Matter.
39. FlickrSetTag by Thomas Mango : Generates image galleries from Flickr sets.
40. Projectlist by Frederic Hemberger : Loads all files from a directory and renders the entries into a single page, instead of creating separate posts.
41. Tiered Archives by Eli Naeher : creates a tiered template variable that allows you to create archives grouped by year and month.
42. Jammit generator by Vladimir Andrijevik : enables use of Jammit for JavaScript and CSS packaging.
43. oEmbed Tag by Tammo van Lessen : enables easy content embedding (e.g. from YouTube, Flickr, Slideshare) via oEmbed.
44. Company website and blog plugins by Flatterline, a Ruby on Rails development company : portfolio/project page generator, team/individual page generator, author bio liquid template tag for use on posts and a few other smaller plugins.
45. Transform Layouts Monkey patching allowing HAML layouts (you need a HAML Converter plugin for this to work)
46. ReStructuredText converter : Converts ReST documents to HTML with Pygments syntax highlighting.
47. Tweet Tag by Scott W. Bradley : Liquid tag for Embedded Tweets using Twitter’s shortcodes
48. jekyll-localization : Jekyll plugin that adds localization features to the rendering engine.
49. jekyll-rendering : Jekyll plugin to provide alternative rendering engines.
50. jekyll-pagination : Jekyll plugin to extend the pagination generator.
51. jekyll-tagging : Jekyll plugin to automatically generate a tag cloud and tag pages.
52. Generate YouTube Embed by joelverhagen : Jekyll plugin which allows you to embed a YouTube video in your page with the YouTube ID. Optionally specify width and height dimensions. Like “oEmbed Tag” but just for YouTube.
53. JSON Filter by joelverhagen : filter that takes input text and outputs it as JSON. Great for rendering JavaScript.
54. jekyll-beastiepress : FreeBSD utility tags for Jekyll sites.
55. jsonball : reads json files and produces maps for use in jekylled files
56. redcarpet2 : use Redcarpet2 for rendering markdown
57. bibjekyll : render BibTeX-formatted bibliographies/citations included in posts/pages using bibtex2html
58. jekyll-citation : render BibTeX-formatted bibliographies/citations included in posts/pages (pure Ruby)
59. jekyll-scholar : Jekyll extensions for the blogging scholar
60. jekyll-asset_bundler : bundles and minifies JavaScript and CSS
61. Jekyll Dribbble Set Tag : builds Dribbble image galleries from any user
62. debbugs : allows posting links to Debian BTS easily
63. refheap_tag : Liquid tag that allows embedding pastes from refheap
64. i18n_filter : Liquid filter to use I18n localization.
65. singlepage-jekyll by JCB-K : turns Jekyll into a dynamic one-page website.
66. flickr : Embed photos from flickr right into your posts.
67. jekyll-devonly_tag : A block tag for including markup only during development.
68. Jekyll plugins by Aucor : Plugins for eg. trimming unwanted newlines/whitespace and sorting pages by weight attribute.
69. Only first paragraph : Show only first paragrpaph of page/post.