dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rewrite documentation on installing plugins (#8921) 

Merge pull request 8921
This commit is contained in:
Ashwin Maroli 2022-01-06 20:46:00 +05:30 committed by GitHub
parent 1008f1b4e3
commit b0a68d56fc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 100 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
docs/_docs/plugins/installation.md
View File

@ -3,77 +3,123 @@ title: Plugins
permalink: /docs/plugins/installation/
---
You have 3 options for installing plugins:
Jekyll has built-in support for using plugins to extend the core functionality.
1. In your site source root, make a `_plugins` directory. Place your plugins
here. Any file ending in `*.rb` inside this directory will be loaded before
Jekyll generates your site.
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.
2. In your `_config.yml` file, add a new array with the key `plugins` (or `gems` for Jekyll < `3.5.0`) and the
values of the gem names of the plugins you'd like to use. An example:
This behavior can be configured as follows:
```yaml
# This will require each of these plugins automatically.
plugins:
- jekyll-gist
- jekyll-coffeescript
- jekyll-assets
- another-jekyll-plugin
```
- 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.
Then install your plugins using `gem install jekyll-gist jekyll-coffeescript jekyll-assets another-jekyll-plugin`
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:
3. Add the relevant plugins to a Bundler group in your `Gemfile`. An
example:
```yaml
plugins:
- jekyll-gist
- jekyll-coffeescript
- jekyll-seo-tag
- some-other-jekyll-plugin
```ruby
group :jekyll_plugins do
gem "jekyll-gist"
gem "jekyll-coffeescript"
gem "jekyll-assets"
gem "another-jekyll-plugin"
end
```
# Enable safe mode
safe: true
Now you need to install all plugins from your Bundler group by running single command `bundle install`.
# 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 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 to GitHub Pages.<br><br>
You can still use GitHub Pages to publish your site, but you’ll need to
convert the site locally and push the generated static files to your GitHub
repository instead of the Jekyll source files.
<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 build the site locally and push the generated files to your
GitHub repository instead of the Jekyll source files.
</p>
</div>
<div class="note">
<h5>
<code>_plugins</code>, <code>_config.yml</code> and <code>Gemfile</code>
can be used simultaneously
<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 options simultaneously in the
same site if you so choose. Use of one does not restrict the use of the
others.
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>
### The jekyll_plugins group
Jekyll gives this particular group of gems in your `Gemfile` a different
treatment. Any gem included in this group is loaded before Jekyll starts
processing the rest of your source directory.
A gem included here will be activated even if its not explicitly listed under
the `plugins:` key in your site's config file.
{: .note .warning}
Gems included in the <code>:jekyll-plugins</code> group are activated
regardless of the <code>--safe</code> mode setting. Be aware of which
gems are included under this group!