add `plugins` config key as replacement for `gems` (#5130)

Merge pull request 5130

docs/_docs/assets.md

@@ -88,6 +88,6 @@ To enable Coffeescript in Jekyll 3.0 and up you must
 * Ensure that your `_config.yml` is up-to-date and includes the following:
 
 ```yaml
-gems:
+plugins:
  - jekyll-coffeescript
 ```

docs/_docs/configuration.md

@@ -616,7 +616,7 @@ unpublished: false
 
 # Plugins
 whitelist: []
-gems:      []
+plugins:   []
 
 # Conversion
 markdown:    kramdown

docs/_docs/plugins.md

@@ -27,12 +27,12 @@ You have 3 options for installing plugins:
 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.
-2. In your `_config.yml` file, add a new array with the key `gems` and the
+2. In your `_config.yml` file, add a new array with the key `plugins` and the
 values of the gem names of the plugins you'd like to use. An example:
 
 
-        gems: [jekyll-coffeescript, jekyll-watch, jekyll-assets]
-        # This will require each of these gems automatically.
+        plugins: [jekyll-coffeescript, jekyll-watch, jekyll-assets]
+        # This will require each of these plugins automatically.
 
     Then install your plugins using `gem install jekyll-coffeescript jekyll-watch jekyll-assets`
 

lib/jekyll/configuration.rb

@@ -33,7 +33,7 @@ module Jekyll
 
       # Plugins
       "whitelist"         => [],
-      "gems"              => [],
+      "plugins"           => [],
 
       # Conversion
       "markdown"          => "kramdown",
@@ -229,9 +229,10 @@ module Jekyll
       # Provide backwards-compatibility
       check_auto(config)
       check_server(config)
+      check_plugins(config)
 
       renamed_key "server_port", "port", config
-      renamed_key "plugins", "plugins_dir", config
+      renamed_key "gems", "plugins", config
       renamed_key "layouts", "layouts_dir", config
       renamed_key "data_source", "data_dir", config
 
@@ -385,5 +386,24 @@ module Jekyll
           "`_config.yml` file."
       end
     end
+
+    # Private: Checks if the `plugins` config is a String
+    #
+    # config - the config hash
+    #
+    # Raises a Jekyll::Errors::InvalidConfigurationError if the config `plugins`
+    # is a string
+    private
+    def check_plugins(config)
+      if config.key?("plugins") && config["plugins"].is_a?(String)
+        Jekyll.logger.error "Configuration Error:", "You specified the" \
+          " `plugins` config in your configuration file as a string, please" \
+          " use an array instead. If you wanted to set the directory of your" \
+          " plugins, use the config key `plugins_dir` instead."
+        raise Jekyll::Errors::InvalidConfigurationError,
+          "'plugins' should not be a string, but was: " \
+          "#{config["plugins"].inspect}. Use 'plugins_dir' instead."
+      end
+    end
   end
 end

lib/jekyll/errors.rb

@@ -9,9 +9,10 @@ module Jekyll
     InvalidYAMLFrontMatterError = Class.new(FatalException)
     MissingDependencyException  = Class.new(FatalException)
 
-    InvalidDateError      = Class.new(FatalException)
-    InvalidPostNameError  = Class.new(FatalException)
-    PostURLError          = Class.new(FatalException)
-    InvalidURLError       = Class.new(FatalException)
+    InvalidDateError            = Class.new(FatalException)
+    InvalidPostNameError        = Class.new(FatalException)
+    PostURLError                = Class.new(FatalException)
+    InvalidURLError             = Class.new(FatalException)
+    InvalidConfigurationError   = Class.new(FatalException)
   end
 end

lib/jekyll/plugin_manager.rb

@@ -26,7 +26,7 @@ module Jekyll
     # Returns nothing.
     def require_gems
       Jekyll::External.require_with_graceful_fail(
-        site.gems.select { |gem| plugin_allowed?(gem) }
+        site.gems.select { |plugin| plugin_allowed?(plugin) }
       )
     end
 
@@ -59,12 +59,12 @@ module Jekyll
 
     # Check whether a gem plugin is allowed to be used during this build.
     #
-    # gem_name - the name of the gem
+    # plugin_name - the name of the plugin
     #
-    # Returns true if the gem name is in the whitelist or if the site is not
+    # Returns true if the plugin name is in the whitelist or if the site is not
     #   in safe mode.
-    def plugin_allowed?(gem_name)
-      !site.safe || whitelist.include?(gem_name)
+    def plugin_allowed?(plugin_name)
+      !site.safe || whitelist.include?(plugin_name)
     end
 
     # Build an array of allowed plugin gem names.
@@ -99,12 +99,12 @@ module Jekyll
     end
 
     def deprecation_checks
-      pagination_included = (site.config["gems"] || []).include?("jekyll-paginate") ||
+      pagination_included = (site.config["plugins"] || []).include?("jekyll-paginate") ||
         defined?(Jekyll::Paginate)
       if site.config["paginate"] && !pagination_included
         Jekyll::Deprecator.deprecation_message "You appear to have pagination " \
           "turned on, but you haven't included the `jekyll-paginate` gem. " \
-          "Ensure you have `gems: [jekyll-paginate]` in your configuration file."
+          "Ensure you have `plugins: [jekyll-paginate]` in your configuration file."
       end
     end
   end

lib/jekyll/site.rb

@@ -46,10 +46,13 @@ module Jekyll
       @config = config.clone
 
       %w(safe lsi highlighter baseurl exclude include future unpublished
-        show_drafts limit_posts keep_files gems).each do |opt|
+        show_drafts limit_posts keep_files).each do |opt|
         self.send("#{opt}=", config[opt])
       end
 
+      # keep using `gems` to avoid breaking change
+      self.gems = config["plugins"]
+
       configure_plugins
       configure_theme
       configure_include_paths

test/test_configuration.rb

@@ -205,9 +205,9 @@ class TestConfiguration < JekyllUnitTest
         "exclude"     => "READ-ME.md, Gemfile,CONTRIBUTING.hello.markdown",
         "include"     => "STOP_THE_PRESSES.txt,.heloses, .git",
         "pygments"    => true,
-        "plugins"     => true,
         "layouts"     => true,
         "data_source" => true,
+        "gems"        => [],
       }]
     end
     should "unset 'auto' and 'watch'" do
@@ -242,9 +242,6 @@ class TestConfiguration < JekyllUnitTest
       assert_equal @config.backwards_compatibilize["highlighter"], "pygments"
     end
     should "adjust directory names" do
-      assert @config.key?("plugins")
-      assert !@config.backwards_compatibilize.key?("plugins")
-      assert @config.backwards_compatibilize["plugins_dir"]
       assert @config.key?("layouts")
       assert !@config.backwards_compatibilize.key?("layouts")
       assert @config.backwards_compatibilize["layouts_dir"]
@@ -252,6 +249,17 @@ class TestConfiguration < JekyllUnitTest
       assert !@config.backwards_compatibilize.key?("data_source")
       assert @config.backwards_compatibilize["data_dir"]
     end
+    should "raise an error if `plugins` key is a string" do
+      config = Configuration[{ "plugins" => "_plugin" }]
+      assert_raises Jekyll::Errors::InvalidConfigurationError do
+        config.backwards_compatibilize
+      end
+    end
+    should "set the `gems` config to `plugins`" do
+      assert @config.key?("gems")
+      assert !@config.backwards_compatibilize["gems"]
+      assert @config.backwards_compatibilize["plugins"]
+    end
   end
   context "#fix_common_issues" do
     setup do

test/test_plugin_manager.rb

@@ -132,7 +132,7 @@ class TestPluginManager < JekyllUnitTest
 
     should "print no deprecation warning if jekyll-paginate is present" do
       site = double({
-        :config => { "paginate" => true, "gems" => ["jekyll-paginate"] },
+        :config => { "paginate" => true, "plugins" => ["jekyll-paginate"] },
       })
       plugin_manager = PluginManager.new(site)