Improve this page

Jekyll 安装插件和使用插件（Plugins）

Jekyll 内置支持使用插件来扩展核心功能。

通常，任何放置在站点 source 目录下的 _plugins 文件夹中的 .rb 后缀文件，都会在构建过程中自动加载。

这一行为可以通过以下方式进行配置：

  • _plugins 目录可以通过命令行直接或通过配置文件进行更改。
  • 当 Jekyll 运行在 safe 模式下时，位于 _plugins 目录（或其等效目录）的插件将不会被加载。
  • 这个方法不能用于扩展 Jekyll CLI。

要使用打包为 gem 的插件，需要在配置文件中列出所需的 gem，并放置在一个名为 plugins 的顶级键下。此外，如果你在 safe 模式下构建，gem 需要列在名为 whitelist 的顶级键下。例如：

plugins:
  - jekyll-gist
  - jekyll-coffeescript
  - jekyll-seo-tag
  - some-other-jekyll-plugin

# 启用安全模式
safe: true

# 在安全模式下允许的插件。
# 注意 `some-other-jekyll-plugin` 没有列在这里，因此它在安全模式下不会被加载。
whitelist:
  - jekyll-gist
  - jekyll-coffeescript
  - jekyll-seo-tag

如果没有 Gemfile，你需要手动确保在调用 Jekyll 之前已安装列出的插件。例如，可以通过运行以下命令将上面列表中 gem 的最新版本安装到系统范围的位置：

gem install jekyll-gist jekyll-coffeescript jekyll-remote-theme some-other-jekyll-plugin

使用 Gemfile

通过使用 Gemfile（通常位于站点源代码的根目录）并配合使用名为 bundler 的 Ruby gem，可以大大简化各种 gem 依赖的维护。然而，Gemfile 应该 列出你网站的所有主要依赖项，包括 Jekyll 本身，而不仅仅是网站的基于 gem 的插件，因为 Bundler 会通过评估 Gemfile 来缩小已安装的 gem 范围，只解决 运行时依赖。例如：

source "https://rubygems.org"

# 使用最新版本。
gem "jekyll"

# 当前站点的主题，锁定到特定版本。
gem "minima", "2.4.1"

# 在构建过程中加载的插件，具有正确的站点配置。
gem "jekyll-gist"
gem "jekyll-coffeescript"
gem "jekyll-seo-tag", "~> 1.5"
gem "some-other-jekyll-plugin"

# `_plugins` 目录中自定义插件的依赖。
gem "nokogiri", "~> 1.11"

可以通过简单地运行 bundle install 来集体安装 Gemfile 中列出的 gems。

:jekyll_plugins Gemfile 组

Jekyll 对作为 Gemfile 中 :jekyll_plugins 组一部分列出的 gems 给予特别处理。该组下的任何 gem 都会在任何 Jekyll 进程的最开始加载，无论 --safe CLI 标志或配置文件中的条目如何。

尽管此方法允许你通过增加附加子命令和选项来增强 Jekyll 的 CLI，或者避免在配置文件中列出 gems，但缺点是需要留意哪些 gem 被包含在该组中。例如：

source "https://rubygems.org"

# 使用最新版本。
gem "jekyll"

# 当前站点的主题，锁定到特定版本。
gem "minima", "2.4.1"

# 只有在正确配置时才会加载的插件。
gem "jekyll-gist"
gem "jekyll-coffeescript"

# 无论站点配置如何，都会加载的 gem。
group :jekyll_plugins do
  gem "jekyll-cli-plus"
  gem "jekyll-seo-tag", "~> 1.5"
  gem "some-other-jekyll-plugin"
end
GitHub Pages 上的插件

GitHub Pages 是由 Jekyll 提供支持的。所有 GitHub Pages 网站都使用 --safe 选项生成，以禁用插件（某些 被白名单的插件除外），出于安全原因。不幸的是，这意味着如果你通过 GitHub Pages 部署，你的插件将无法正常工作。

你仍然可以使用 GitHub Pages 发布你的网站，但你需要在本地构建网站，然后将生成的文件推送到 GitHub 仓库，而不是 Jekyll 源文件。

_plugins、_config.yml 和 Gemfile 可以同时使用

如果你愿意，可以在同一个站点中同时使用上述任意插件方式。使用其中一种方式并不会限制其他方式的使用。