×
关于

开始旅程

快速指南安装基本用法目录结构配置

编辑内容

头信息撰写博客使用草稿创建页面常用变量Data FilesAssets博客迁移

定制

模板永久链接分页功能插件附加功能

部署

GitHub Pages部署方法

杂项

常见问题使用 Jekyll 的站点相关资源升级

元信息

贡献

插件

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

在 GitHub Pages 使用插件

GitHub Pages 是由 Jekyll 提供技术支持的，考虑到安全因素，所有的 Pages 通过 --safe 选项禁用了插件功能，因此如果你的网站部署在 Github Pages ，那么你的插件不会工作。

不过仍然有办法发布到 GitHub Pages，你只需在本地做一些转换，并把生成好的文件上传到 Github 替代 Jekyll 就可以了。

安装插件

有两种安装插件的方式：

  1. 在网站根下目录建立 _plugins 文件夹，插件放在这里即可。 Jekyll 运行之前，会加载此目录下所有以 *.rb 结尾的文件。

  2. 在 _config.yml 文件中，添加一个以 gems 作为 key 的数组，数组中存放插件的 gem 名称。例如：
 gems: [jekyll-test-plugin, jekyll-jsonify, jekyll-assets]
 # This will require each of these gems automatically.

_plugins and gems 可以同时使用。

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

通常，插件最终会被放在以下的目录中：

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

生成器只需要实现一个方法：

METHOD DESCRIPTION
generate Generates content as a side-effect.

转换器

如果想使用一个新的标记语言，可以用你自己的转换器实现，Markdown 和 Textile 就是这样实现的。

记住你的 YAML 头信息

Jekyll 只会转换带有 YAML 头信息的文件，即使你使用了插件也不行。

下边的例子实现了一个转换器，他会用 UpcaseConverter 来转换所有以 .upcase 结尾的文件。

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 个方法：

在上边的例子中， UpcaseConverter#matches检查文件后缀名是不是 .upcase ; UpcaseConverter#convert 会处理检查成功文件的内容，即将所有的字符串变成大写；最终，保存的结果 将以作为后缀名 .html 。

标记

如果你想使用 liquid 标记，你可以这样做。 Jekyll 官方的例子有 highlight 和 include 等标记。下边的例子中，自定义了一个 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 标记最少需要实现如下方法：

你必须同时用 Liquid 模板引擎注册自定义标记，比如：：

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

对于上边的例子，你可以把如下标记放在页面的任何位置：

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

我们在页面上会得到如下内容：

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

Liquid 过滤器

你可以像上边那样在 Liquid 模板中加入自己的过滤器。过滤器会把自己的方法暴露给 liquid 。所有的方法 都必须至少接收一个参数，用来传输入内容；返回值是过滤的结果。

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 对象

Jekyll 允许通过 Liquid 的 context.registers 特性来访问 site 对象。比如可以用context.registers.config 访问配置文件 _config.yml 。

Flags

当写插件时，有两个标记需要注意：

已上边例子的插件为例，应该这样设置这两个标记：

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

可用的插件

下边的插件，你可以按需所取：

生成器

转换器

过滤器

标签

集合

其他

期待你的作品

如果你有一个 Jekyll 插件并且愿意加到这个列表中来，可以阅读此须知，并参照着来做。

分类导航

关注微信下载离线手册

bootwiki移动版 bootwiki
(群号：472910771)