1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
---
title: Plugins
permalink: /docs/plugins/installation/
---
Jekyll has built-in support for using plugins to extend the core functionality.
Primarily, any file with extension `.rb` placed within a `_plugins` directory at the root of the site's `source`, will be automatically loaded
during a build session.
This behavior can be configured as follows:
- The `_plugins` directory may be changed either directly via the command-line or via the configuration file(s).
- Plugins in the `_plugins` directory (or its equivalent(s)) will not be loaded when Jekyll is running in `safe` mode.
- This route cannot be used to extend the Jekyll CLI.
To work with plugins packaged as gems, one has to list the desired gems in the configuration file under a top-level key named `plugins`.
Additionally, if you're building in `safe` mode, the gem needs to be listed under a top-level key named `whitelist`. For example:
```yaml
plugins:
- jekyll-gist
- jekyll-coffeescript
- jekyll-seo-tag
- some-other-jekyll-plugin
# Enable safe mode
safe: true
# Whitelist plugins under safe mode.
# Note that `some-other-jekyll-plugin` is not listed here. Therefore,
# it will not be loaded under safe mode.
whitelist:
- jekyll-gist
- jekyll-coffeescript
- jekyll-seo-tag
```
In the absence of a Gemfile, one must manually ensure that listed plugins have been installed prior to invoking Jekyll. For example, the
latest versions of gems in the above list may be installed to a system-wide location by running:
```sh
gem install jekyll-gist jekyll-coffeescript jekyll-remote-theme some-other-jekyll-plugin
```
## Using a Gemfile
The maintenance of various gem dependencies may be greatly simplified by using a Gemfile (usually at the root of the site's source) in
conjunction with a Rubygem named `bundler`. The Gemfile however **should** list all the primary dependencies of your site, including Jekyll
itself, not just gem-based plugins of the site because Bundler narrows the scope of installed gems to just *runtime dependencies* resolved by
evaluating the Gemfile. For example:
```ruby
source "https://rubygems.org"
# Use the latest version.
gem "jekyll"
# The theme of current site, locked to a certain version.
gem "minima", "2.4.1"
# Plugins of this site loaded during a build with proper
# site configuration.
gem "jekyll-gist"
gem "jekyll-coffeescript"
gem "jekyll-seo-tag", "~> 1.5"
gem "some-other-jekyll-plugin"
# A dependency of a custom-plugin inside `_plugins` directory.
gem "nokogiri", "~> 1.11"
```
The gems listed in the Gemfile can be collectively installed by simply running `bundle install`.
### The `:jekyll_plugins` Gemfile group
{: #the-jekyll_plugins-group}
Jekyll gives a special treatment to gems listed as part of the `:jekyll_plugins` group in a Gemfile. Any gem under this group is loaded at
the very beginning of any Jekyll process, irrespective of the `--safe` CLI flag or entries in the configuration file(s).
While this route allows one to enhance Jekyll's CLI with additional subcommands and options, or avoid having to list gems in the configuration
file, the downside is the necessity to be mindful of what gems are included in the group. For example:
```ruby
source "https://rubygems.org"
# Use the latest version.
gem "jekyll"
# The theme of current site, locked to a certain version.
gem "minima", "2.4.1"
# Plugins of this site loaded only if configured correctly.
gem "jekyll-gist"
gem "jekyll-coffeescript"
# Gems loaded irrespective of site configuration.
group :jekyll_plugins do
gem "jekyll-cli-plus"
gem "jekyll-seo-tag", "~> 1.5"
gem "some-other-jekyll-plugin"
end
```
<div class="note info">
<h5>Plugins on GitHub Pages</h5>
<p>
<a href="https://pages.github.com/">GitHub Pages</a> is powered by Jekyll. All GitHub Pages sites are generated using the
<code>--safe</code> option to disable plugins (with the exception of some
<a href="https://pages.github.com/versions">whitelisted plugins</a>) for security reasons. Unfortunately, this means your plugins won't
work if you’re deploying via GitHub Pages.<br><br>
You can still use GitHub Pages to publish your site, but you'll need to either build the site locally and push the generated files to
your GitHub repository or use
<a href="{{ '/docs/continuous-integration/github-actions/' | relative_url }}" title="GitHub Actions">GitHub Actions</a> to host source
files on GitHub yet build and deploy with full control on GitHub Pages.
</p>
</div>
<div class="note">
<h5>
<code>_plugins</code>, <code>_config.yml</code> and <code>Gemfile</code> can be used simultaneously
</h5>
<p>
You may use any of the aforementioned plugin routes simultaneously in the same site if you so choose.
Use of one does not restrict the use of the others.
</p>
</div>
|
