Merge pull request #2884 from gjtorikian/improve-docs-for-include-relative

lib/jekyll/tags/include.rb

@@ -13,8 +13,6 @@ module Jekyll
 
     class IncludeTag < Liquid::Tag
 
-      SYNTAX_EXAMPLE = "{% include file.ext param='value' param2='value' %}"
-
       VALID_SYNTAX = /([\w-]+)\s*=\s*(?:"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|([\w\.-]+))/
       VARIABLE_SYNTAX = /(?<variable>[^{]*\{\{\s*(?<name>[\w\-\.]+)\s*(\|.*)?\}\}[^\s}]*)(?<params>.*)/
 
@@ -28,6 +26,11 @@ module Jekyll
           @file, @params = markup.strip.split(' ', 2);
         end
         validate_params if @params
+        @tag_name = tag_name
+      end
+
+      def syntax_example
+        "{% #{@tag_name} file.ext param='value' param2='value' %}"
       end
 
       def parse_params(context)
@@ -59,7 +62,7 @@ Invalid syntax for include tag. File contains invalid characters or sequences:
 
 Valid syntax:
 
-  #{SYNTAX_EXAMPLE}
+  #{syntax_example}
 
 eos
         end
@@ -75,7 +78,7 @@ Invalid syntax for include tag:
 
 Valid syntax:
 
-  #{SYNTAX_EXAMPLE}
+  #{syntax_example}
 
 eos
         end

site/_docs/templates.md

@@ -292,16 +292,22 @@ These parameters are available via Liquid in the include:
 {% raw %}{{ include.param }}{% endraw %}
 {% endhighlight %}
 
-### Including files relative to another file
+#### Including files relative to another file
 
-You can also choose to include files relative to the current file:
+You can also choose to include file fragments relative to the current file:
 
 {% highlight ruby %}
 {% raw %}{% include_relative somedir/footer.html %}{% endraw %}
 {% endhighlight %}
 
-You won't need to place your included content within the `_includes` directory.
-All the other capaibilities of the `include` tag are available to the `include_relative` tag.
+You won't need to place your included content within the `_includes` directory. Instead,
+the inclusion is specifically relative to the file where the tag is being used. For example,
+if `_posts/2014-09-03-my-file.markdown` uses the `include_relative` tag, the included file
+must be within the `_posts` directory, or one of it's subdirectories. You cannot include
+files in other locations.
+
+All the other capaibilities of the `include` tag are available to the `include_relative` tag,
+such as using variables.
 
 ### Code snippet highlighting
 

test/test_tags.rb

@@ -568,6 +568,25 @@ CONTENT
           assert_equal 'Included file \'./missing.html\' not found', exception.message
         end
       end
+
+      context "include existing file above you" do
+        setup do
+          @content = <<CONTENT
+---
+title: higher file
+---
+
+{% include_relative ../README.markdown %}
+CONTENT
+        end
+
+        should "raise error relative to source directory" do
+          exception = assert_raise ArgumentError do
+            create_post(@content, {'permalink' => 'pretty', 'source' => source_dir, 'destination' => dest_dir, 'read_posts' => true})
+          end
+          assert_equal "Invalid syntax for include tag. File contains invalid characters or sequences:\n\n  ../README.markdown\n\nValid syntax:\n\n  {% include_relative file.ext param='value' param2='value' %}\n\n", exception.message
+        end
+      end
     end
 
     context "with symlink'd include" do