鍍金池/ 教程/ Java/ 插件
Assets
相關(guān)資源
創(chuàng)建頁面
基本用法
常見問題
模板
升級(jí)
配置
部署方法
使用 Jekyll 的站點(diǎn)
頭信息
插件
博客遷移
永久鏈接
使用草稿
貢獻(xiàn)
分頁功能
安裝
目錄結(jié)構(gòu)
Data Files
常用變量
GitHub Pages
撰寫博客
快速指南
附加功能

插件

Jekyll 支持插件功能，你可以很容易的加入自己的代碼。

在 GitHub Pages 使用插件

GitHub Pages 是由 Jekyll 提供技術(shù)支持的，考慮到安全因素，所有的 Pages 通過 --safe 選項(xiàng)禁用了插件功能，因此如果你的網(wǎng)站部署在 Github Pages ，那么你的插件不會(huì)工作。

不過仍然有辦法發(fā)布到 GitHub Pages，你只需在本地做一些轉(zhuǎn)換，并把生成好的文件上傳到 Github 替代 Jekyll 就可以了。

安裝插件

有兩種安裝插件的方式：

  1. 在網(wǎng)站根下目錄建立 _plugins 文件夾，插件放在這里即可。 Jekyll 運(yùn)行之前，會(huì)加載此目錄下所有以 *.rb 結(jié)尾的文件。

  2. 在 _config.yml 文件中，添加一個(gè)以 gems 作為 key 的數(shù)組，數(shù)組中存放插件的 gem 名稱。例如：
 gems: [jekyll-test-plugin, jekyll-jsonify, jekyll-assets]
 # This will require each of these gems automatically.

_plugins and gems 可以同時(shí)使用。

You may use both of the aforementioned plugin options simultaneously in the same site if you so choose. Use of one does not restrict the use of the other

通常，插件最終會(huì)被放在以下的目錄中：

  1. Generators
  2. Converters
  3. Tags

生成器

You can create a generator when you need Jekyll to create additional content based on your own rules.

A generator is a subclass of Jekyll::Generator that defines a generate method, which receives an instance of Jekyll::Site.

Generation is triggered for its side-effects, the return value of generate is ignored. Jekyll does not assume any particular side-effect to happen, it just runs the method.

Generators run after Jekyll has made an inventory of the existing content, and before the site is generated. Pages with YAML front-matters are stored as instances of Jekyll::Page and are available via site.pages. Static files become instances of Jekyll::StaticFile and are available via site.static_files. See Jekyll::Site for more details.

For instance, a generator can inject values computed at build time for template variables. In the following example the template reading.html has two variables ongoing and donethat we fill in the generator:

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

This is a more complex generator that generates new pages:

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 列出所有的文章。

生成器只需要實(shí)現(xiàn)一個(gè)方法：

METHOD DESCRIPTION
generate Generates content as a side-effect.

轉(zhuǎn)換器

如果想使用一個(gè)新的標(biāo)記語言，可以用你自己的轉(zhuǎn)換器實(shí)現(xiàn)，Markdown 和 Textile 就是這樣實(shí)現(xiàn)的。

記住你的 YAML 頭信息

Jekyll 只會(huì)轉(zhuǎn)換帶有 YAML 頭信息的文件，即使你使用了插件也不行。

下邊的例子實(shí)現(xiàn)了一個(gè)轉(zhuǎn)換器，他會(huì)用 UpcaseConverter 來轉(zhuǎn)換所有以 .upcase 結(jié)尾的文件。

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

轉(zhuǎn)換器需要最少實(shí)現(xiàn)以下 3 個(gè)方法：

http://wiki.jikexueyuan.com/project/jekyll/images/16.png" alt="" />

在上邊的例子中， UpcaseConverter#matches檢查文件后綴名是不是 .upcase ; UpcaseConverter#convert 會(huì)處理檢查成功文件的內(nèi)容，即將所有的字符串變成大寫；最終，保存的結(jié)果 將以作為后綴名 .html 。

標(biāo)記

如果你想使用 liquid 標(biāo)記，你可以這樣做。 Jekyll 官方的例子有 highlight 和 include 等標(biāo)記。下邊的例子中，自定義了一個(gè) liquid 標(biāo)記，用來輸出當(dāng)前時(shí)間：

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 標(biāo)記最少需要實(shí)現(xiàn)如下方法：

http://wiki.jikexueyuan.com/project/jekyll/images/17.png" alt="" />

你必須同時(shí)用 Liquid 模板引擎注冊(cè)自定義標(biāo)記，比如：：

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

對(duì)于上邊的例子，你可以把如下標(biāo)記放在頁面的任何位置：

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

我們?cè)陧撁嫔蠒?huì)得到如下內(nèi)容：

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

Liquid 過濾器

你可以像上邊那樣在 Liquid 模板中加入自己的過濾器。過濾器會(huì)把自己的方法暴露給 liquid 。所有的方法 都必須至少接收一個(gè)參數(shù)，用來傳輸入內(nèi)容；返回值是過濾的結(jié)果。

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 訪問 site 對(duì)象

Jekyll 允許通過 Liquid 的 context.registers 特性來訪問 site 對(duì)象。比如可以用context.registers.config 訪問配置文件 _config.yml 。

Flags

當(dāng)寫插件時(shí)，有兩個(gè)標(biāo)記需要注意：

http://wiki.jikexueyuan.com/project/jekyll/images/18.png" alt="" />

已上邊例子的插件為例，應(yīng)該這樣設(shè)置這兩個(gè)標(biāo)記：

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

可用的插件

下邊的插件，你可以按需所?。?/p>

生成器

轉(zhuǎn)換器

過濾器

標(biāo)簽

集合

其他

期待你的作品

如果你有一個(gè) Jekyll 插件并且愿意加到這個(gè)列表中來，可以閱讀此須知，并參照著來做。

上一篇：升級(jí)下一篇：使用草稿