Make _includes directory configurable; closes jekyll#2684

and rename `plugins`, `layouts` and `data_source` directories for consistency

bin/jekyll

@@ -22,8 +22,8 @@ Mercenary.program(:jekyll) do |p|
   p.option 'source', '-s', '--source [DIR]', 'Source directory (defaults to ./)'
   p.option 'destination', '-d', '--destination [DIR]', 'Destination directory (defaults to ./_site)'
   p.option 'safe', '--safe', 'Safe mode (defaults to false)'
-  p.option 'plugins', '-p', '--plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]', Array, 'Plugins directory (defaults to ./_plugins)'
-  p.option 'layouts', '--layouts DIR', String, 'Layouts directory (defaults to ./_layouts)'
+  p.option 'plugins_dir', '-p', '--plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]', Array, 'Plugins directory (defaults to ./_plugins)'
+  p.option 'layouts_dir', '--layouts DIR', String, 'Layouts directory (defaults to ./_layouts)'
 
   Jekyll::Command.subclasses.each { |c| c.init_with_program(p) }
 

features/site_configuration.feature

@@ -224,7 +224,7 @@ Feature: Site configuration
       | key         | value        |
       | time        | 2010-01-01   |
       | future      | true         |
-      | layouts     | _theme       |
+      | layouts_dir | _theme       |
     And I have a _posts directory
     And I have the following posts:
       | title  | date       | layout | content             |

lib/jekyll/configuration.rb

@@ -9,9 +9,10 @@ class Configuration < Hash
       # Where things are
       'source'        => Dir.pwd,
       'destination'   => File.join(Dir.pwd, '_site'),
-      'plugins'       => '_plugins',
-      'layouts'       => '_layouts',
-      'data_source'   =>  '_data',
+      'plugins_dir'   => '_plugins',
+      'layouts_dir'   => '_layouts',
+      'data_dir'      => '_data',
+      'includes_dir'  => '_includes',
       'collections'   => nil,
 
       # Handling Reading
@@ -263,6 +264,33 @@ def backwards_compatibilize
           "`_config.yml` file."
       end
 
+      if config.key? 'plugins'
+        Jekyll::Deprecator.deprecation_message "The 'plugins'" +
+          " configuration option has been renamed to 'plugins_dir'." +
+          " Please update your config file accordingly."
+        # copy but don't overwrite:
+        config['plugins_dir'] = config['plugins'] unless config.key?('plugins_dir')
+        config.delete('plugins')
+      end
+
+      if config.key? 'layouts'
+        Jekyll::Deprecator.deprecation_message "The 'layouts'" +
+          " configuration option has been renamed to 'layouts_dir'." +
+          " Please update your config file accordingly."
+        # copy but don't overwrite:
+        config['layouts_dir'] = config['layouts'] unless config.key?('layouts_dir')
+        config.delete('layouts')
+      end
+
+      if config.key? 'data_source'
+        Jekyll::Deprecator.deprecation_message "The 'data_source'" +
+          " configuration option has been renamed to 'data_dir'." +
+          " Please update your config file accordingly."
+        # copy but don't overwrite:
+        config['data_dir'] = config['data_source'] unless config.key?('data_dir')
+        config.delete('data_source')
+      end
+
       config
     end
 

lib/jekyll/convertible.rb

@@ -211,7 +211,7 @@ def render_all_layouts(layouts, payload, info)
         self.output = render_liquid(layout.content,
                                          payload,
                                          info,
-                                         File.join(site.config['layouts'], layout.name))
+                                         File.join(site.config['layouts_dir'], layout.name))
 
         # Add layout to dependency tree
         site.regenerator.add_dependency(

lib/jekyll/plugin_manager.rb

@@ -82,10 +82,10 @@ def require_plugin_files
     #
     # Returns an Array of plugin search paths
     def plugins_path
-      if (site.config['plugins'] == Jekyll::Configuration::DEFAULTS['plugins'])
-        [site.in_source_dir(site.config['plugins'])]
+      if (site.config['plugins_dir'] == Jekyll::Configuration::DEFAULTS['plugins_dir'])
+        [site.in_source_dir(site.config['plugins_dir'])]
       else
-        Array(site.config['plugins']).map { |d| File.expand_path(d) }
+        Array(site.config['plugins_dir']).map { |d| File.expand_path(d) }
       end
     end
 

lib/jekyll/reader.rb

@@ -16,7 +16,7 @@ def read
       @site.layouts = LayoutReader.new(site).read
       read_directories
       sort_files!
-      @site.data = DataReader.new(site).read(site.config['data_source'])
+      @site.data = DataReader.new(site).read(site.config['data_dir'])
       CollectionReader.new(site).read
     end
 

lib/jekyll/readers/layout_reader.rb

@@ -38,11 +38,11 @@ def within(directory)
     end
 
     def layout_directory_inside_source
-      site.in_source_dir(site.config['layouts'])
+      site.in_source_dir(site.config['layouts_dir'])
     end
 
     def layout_directory_in_cwd
-      dir = Jekyll.sanitized_path(Dir.pwd, site.config['layouts'])
+      dir = Jekyll.sanitized_path(Dir.pwd, site.config['layouts_dir'])
       if File.directory?(dir) && !site.safe
         dir
       else

lib/jekyll/renderer.rb

@@ -138,7 +138,7 @@ def place_in_layouts(content, payload, info)
           layout.content,
           payload,
           info,
-          File.join(site.config['layouts'], layout.name)
+          File.join(site.config['layouts_dir'], layout.name)
         )
 
         # Add layout to dependency tree

lib/jekyll/tags/include.rb

@@ -20,7 +20,6 @@ class IncludeTag < Liquid::Tag
 
       def initialize(tag_name, markup, tokens)
         super
-        @includes_dir = tag_includes_dir
         matched = markup.strip.match(VARIABLE_SYNTAX)
         if matched
           @file = matched['variable'].strip
@@ -100,12 +99,13 @@ def render_variable(context)
         end
       end
 
-      def tag_includes_dir
-        '_includes'.freeze
+      def tag_includes_dir(context)
+        context.registers[:site].config['includes_dir'].freeze
       end
 
       def render(context)
         site = context.registers[:site]
+        @includes_dir = tag_includes_dir(context)
         dir = resolved_includes_dir(context)
 
         file = render_variable(context) || @file
@@ -161,7 +161,7 @@ def read_file(file, context)
     end
 
     class IncludeRelativeTag < IncludeTag
-      def tag_includes_dir
+      def tag_includes_dir(context)
         '.'.freeze
       end
 

site/_docs/configuration.md

@@ -465,12 +465,13 @@ file or on the command-line.
 
 {% highlight yaml %}
 # Where things are
-source:      .
-destination: ./_site
-plugins:     ./_plugins
-layouts:     ./_layouts
-data_source: ./_data
-collections: null
+source:       .
+destination:  ./_site
+plugins_dir:  ./_plugins
+layouts_dir:  ./_layouts
+data_dir:     ./_data
+includes_dir: ./_includes
+collections:  null
 
 # Handling Reading
 safe:         false

test/source/_includes_custom/custom.html

@@ -0,0 +1 @@
+custom_included

test/test_configuration.rb

@@ -66,6 +66,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,
       }]
     end
     should "unset 'auto' and 'watch'" do
@@ -93,6 +96,17 @@ class TestConfiguration < JekyllUnitTest
       assert !@config.backwards_compatibilize.key?("pygments")
       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"]
+      assert @config.key?("data_source")
+      assert !@config.backwards_compatibilize.key?("data_source")
+      assert @config.backwards_compatibilize["data_dir"]
+    end
   end
   context "#fix_common_issues" do
     setup do

test/test_site.rb

@@ -13,22 +13,22 @@ class TestSite < JekyllUnitTest
     end
 
     should "have an array for plugins if passed as a string" do
-      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => '/tmp/plugins'}))
+      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins_dir' => '/tmp/plugins'}))
       assert_equal ['/tmp/plugins'], site.plugins
     end
 
     should "have an array for plugins if passed as an array" do
-      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => ['/tmp/plugins', '/tmp/otherplugins']}))
+      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins_dir' => ['/tmp/plugins', '/tmp/otherplugins']}))
       assert_equal ['/tmp/plugins', '/tmp/otherplugins'], site.plugins
     end
 
     should "have an empty array for plugins if nothing is passed" do
-      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => []}))
+      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins_dir' => []}))
       assert_equal [], site.plugins
     end
 
     should "have an empty array for plugins if nil is passed" do
-      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => nil}))
+      site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins_dir' => nil}))
       assert_equal [], site.plugins
     end
 

test/test_tags.rb

@@ -600,6 +600,23 @@ def highlight_block_with_opts(options_string)
       end
     end
 
+    context "with custom includes directory" do
+      setup do
+        content = <<CONTENT
+---
+title: custom includes directory
+---
+
+{% include custom.html %}
+CONTENT
+        create_post(content, {'includes_dir' => '_includes_custom', 'permalink' => 'pretty', 'source' => source_dir, 'destination' => dest_dir, 'read_posts' => true})
+      end
+
+      should "include file from custom directory" do
+        assert_match "custom_included", @result
+      end
+    end
+
     context "without parameters within if statement" do
       setup do
         content = <<CONTENT