From ccb133fd333e75ddbf51bf26efc5b95085c6e449 Mon Sep 17 00:00:00 2001 From: Florian Thomas Date: Mon, 17 Apr 2017 12:46:33 +0100 Subject: [PATCH] add `plugins` config key as replacement for `gems` (#5130) Merge pull request 5130 --- docs/_docs/assets.md | 2 +- docs/_docs/configuration.md | 2 +- docs/_docs/plugins.md | 6 +++--- lib/jekyll/configuration.rb | 24 ++++++++++++++++++++++-- lib/jekyll/errors.rb | 9 +++++---- lib/jekyll/plugin_manager.rb | 14 +++++++------- lib/jekyll/site.rb | 5 ++++- test/test_configuration.rb | 16 ++++++++++++---- test/test_plugin_manager.rb | 2 +- 9 files changed, 56 insertions(+), 24 deletions(-) diff --git a/docs/_docs/assets.md b/docs/_docs/assets.md index 7418f984..b31cf16c 100644 --- a/docs/_docs/assets.md +++ b/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 ``` diff --git a/docs/_docs/configuration.md b/docs/_docs/configuration.md index 989aa907..7789d52f 100644 --- a/docs/_docs/configuration.md +++ b/docs/_docs/configuration.md @@ -616,7 +616,7 @@ unpublished: false # Plugins whitelist: [] -gems: [] +plugins: [] # Conversion markdown: kramdown diff --git a/docs/_docs/plugins.md b/docs/_docs/plugins.md index 4c09d227..bc6386e2 100644 --- a/docs/_docs/plugins.md +++ b/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` diff --git a/lib/jekyll/configuration.rb b/lib/jekyll/configuration.rb index 1e2ca01c..86bee3c1 100644 --- a/lib/jekyll/configuration.rb +++ b/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 diff --git a/lib/jekyll/errors.rb b/lib/jekyll/errors.rb index 6ae24337..95aa04b4 100644 --- a/lib/jekyll/errors.rb +++ b/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 diff --git a/lib/jekyll/plugin_manager.rb b/lib/jekyll/plugin_manager.rb index fa183c62..979004d6 100644 --- a/lib/jekyll/plugin_manager.rb +++ b/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 diff --git a/lib/jekyll/site.rb b/lib/jekyll/site.rb index 347cea97..64760275 100644 --- a/lib/jekyll/site.rb +++ b/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 diff --git a/test/test_configuration.rb b/test/test_configuration.rb index 9602c5c3..c9988d16 100644 --- a/test/test_configuration.rb +++ b/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 diff --git a/test/test_plugin_manager.rb b/test/test_plugin_manager.rb index 9217965b..90f05764 100644 --- a/test/test_plugin_manager.rb +++ b/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)