Merge branch 'master' into ruby-2.4.0

.travis.yml

@@ -8,7 +8,7 @@ rvm:
   - &ruby1 2.4.0
   - &ruby2 2.3.3
   - &ruby3 2.2.6
-  - &ruby4 2.1.9
+  - &ruby4 2.1.10
   - &jruby jruby-9.1.7.0
 
 matrix:

History.markdown

@@ -3,12 +3,29 @@
 ### Minor Enhancements
 
   * Upgrade to Liquid v4 (#4362)
+  * Convert StaticFile liquid representation to a Drop & add front matter defaults support to StaticFiles (#5871)
 
 ### Documentation
 
   * Install troubleshooting on Ubuntu (#5817)
+  * Add Termux section on troubleshooting (#5837)
+  * fix ial css classes in theme doc (#5876)
 
-## 3.4.0 / 2016-01-27
+### Development Fixes
+
+  * [Rubocop] add missing comma (#5835)
+
+### Site Enhancements
+
+  * Corrected date for version 3.4.0 (#5842)
+  * Add the correct year to the 3.4.0 release date (#5858)
+  * Add documentation about order of interpretation (#5834)
+
+### Bug Fixes
+
+  * Exclude Gemfile by default (#5860)
+
+## 3.4.0 / 2017-01-27
 
 ### Minor Enhancements
 

docs/_docs/history.md

@@ -4,7 +4,7 @@ permalink: "/docs/history/"
 note: This file is autogenerated. Edit /History.markdown instead.
 ---
 
-## 3.4.0 / 2016-01-27
+## 3.4.0 / 2017-01-27
 {: #v3-4-0}
 
 ### Minor Enhancements

docs/_docs/themes.md

@@ -141,7 +141,8 @@ To install a gem-based theme:
    bundle exec jekyll serve
    ```
 
-You can have multiple themes listed in your site's `Gemfile`, but only one theme can be selected in your site's `_config.yml`. {: .note .info }
+You can have multiple themes listed in your site's `Gemfile`, but only one theme can be selected in your site's `_config.yml`. 
+{: .note .info }
 
 If you're publishing your Jekyll site on [GitHub Pages](https://pages.github.com/), note that GitHub Pages supports only some gem-based themes. See [Supported Themes](https://pages.github.com/themes/) in GitHub's documentation to see which themes are supported.
 
@@ -217,7 +218,8 @@ Themes are visual. Show users what your theme looks like by including a screensh
 
 To preview your theme as you're authoring it, it may be helpful to add dummy content in, for example, `/index.html` and `/page.html` files. This will allow you to use the `jekyll build` and `jekyll serve` commands to preview your theme, just as you'd preview a Jekyll site.
 
-If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme. {: .info .note}
+If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme. 
+{: .info .note}
 
 ### Publishing your theme
 

docs/_docs/troubleshooting.md

@@ -65,6 +65,12 @@ sudo emerge -av dev-ruby/rubygems
 On Windows, you may need to install [RubyInstaller
 DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
 
+On Android (with Termux) you can install all requirements by running: 
+
+```sh
+apt update && apt install libffi-dev clang ruby-dev make
+```
+
 On macOS, you may need to update RubyGems (using `sudo` only if necessary):
 
 ```sh

docs/_tutorials/orderofinterpretation.md

@@ -0,0 +1,143 @@
+---
+layout: tutorials
+permalink: /tutorials/orderofinterpretation/
+title: Order of interpretation
+---
+
+Jekyll's main job is to convert your raw text files into a static website. It does this by rendering Liquid, Markdown, and other transforms as it generates the static HTML output.
+
+In this conversion process, it's important to understand Jekyll's order of interpretation. By "order of interpretation," we mean what gets rendered, in what order, and what rules get applied in converting content.
+
+If an element isn't converting, you can troubleshoot the problem by analyzing the order of interpretation.
+
+## Order of interpretations
+
+Jekyll converts your site in the following order:
+
+1. **Site variables**. Jekyll looks across your files and populates [site variables]({% link _docs/variables.md %}), such as `site`, `page`, `post`, and collection objects. (From these objects, Jekyll determines the values for permalinks, tags, categories, and other details.)
+
+2. **Liquid**. Jekyll processes any [Liquid](https://github.com/Shopify/liquid) formatting in pages that contain [front matter]({% link _docs/frontmatter.md %}). You can identify Liquid as follows:
+   * **Liguid tags** start with `{% raw %}{%{% endraw %}` and end with a `{% raw %}%}{% endraw %}`. For example: `{% raw %}{% highlight %}{% endraw %}` or `{% raw %}{% seo %}{% endraw %}`. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, `{% raw %}{% endhighlight %}{% endraw %}`.
+   * **Liquid variables** start and end with double curly braces. For example: `{% raw %}{{ site.myvariable }}{% endraw %}` or `{% raw %}{{ content }}{% endraw %}`.
+   * **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in `{% raw %}{{ "css/main.css" | relative_url }}{% endraw %}`.
+
+3. **Markdown**. Jekyll converts Markdown to HTML using the Markdown filter specified in your config file. Files must have a Markdown file extension and front matter in order for Jekyll to convert them.
+
+4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the `{% raw %}{{ content }}{% endraw %}` tags within the layouts.
+
+5. **Files**. Jekyll writes the generated content into files in the [directory structure]({% link _docs/structure.md %}) in `_site`. Pages, posts, and collections get structured based on their [permalink]({% link _docs/permalinks.md %}) setting. Directories that begin with `_` (such as `_includes` and `_data`) are usually hidden in the output.
+
+## Scenarios where incorrect configurations create problems
+
+For the most part, you don't have to think about the order of interpretation when building your Jekyll site. These details only become important to know when something isn't rendering.
+
+The following scenarios highlight potential problems you might encounter. These problems come from misunderstanding the order of interpretation and can be easily fixed.
+
+### Variable on page not rendered because variable is assigned in layout
+
+In your layout file (`_layouts/default.html`), suppose you have a variable assigned:
+
+```
+{% raw %}{% assign myvar = "joe" %}{% endraw %}
+```
+
+On a page that uses the layout, you reference that variable:
+
+```
+{% raw %}{{ myvar }}{% endraw %}
+```
+
+The variable won't render because the page's order of interpretation is to render Liquid first and later process the Layout. When the Liquid rendering happens, the variable assignment isn't available.
+
+To make the code work, you could put the variable assignment into the page's front matter.
+
+### Markdown in include file not processed
+
+Suppose you have a Markdown file at `_includes/mycontent.md`. In the Markdown file, you have some Markdown formatting:
+
+```markdown
+This is a list:
+* first item
+* second item
+```
+
+You include the file into an HTML file as follows:
+
+```liquid
+{% raw %}{% include mycontent.md %}{% endraw %}
+```
+
+The Markdown is not processed because first the Liquid (`include` tag) gets processed, inserting `mycontent.md` into the HTML file. *Then* the Markdown would get processed.
+
+But because the content is included into an *HTML* page, the Markdown isn't rendered. The Markdown filter processes content only in Markdown files.
+
+To make the code work, use HTML formatting in includes that are inserted into HTML files.
+
+Note that `highlight` tags don't require Markdown to process. Suppose your include contains the following:
+
+```liquid
+{% raw %}{% highlight javascript %}
+console.log('alert');
+{% endhighlight %}{% endraw %}
+```
+
+The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments for syntax highlighting.) As a result, this code will actually convert to HTML with syntax highlighting. Jekyll does not need the Markdown filter to process `highlight` tags.
+
+### Liquid mixed with JavaScript isn't rendered
+
+Suppose you try to mix Liquid's `assign` tag with JavaScript, like this:
+
+```javascript
+{% raw %}<button onclick="someFunction()">Click me</button>
+
+<p id="intro"></p>
+
+<script>
+{% assign someContent = "This is some content" %}
+function someFunction() {
+    document.getElementById("intro").innerHTML = someContent;
+}
+</script>{% endraw %}
+```
+
+This won't work because the `assign` tag is only available during the Liquid rendering phase of the site. In this JavaScript example, the script executes when a user clicks a button ("Click me") on the HTML page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything.
+
+However, you can use Jekyll's site variables or Liquid to *populate* a script that is executed at a later time. For example, suppose you have the following property in your front matter: `someContent: "This is some content"`. You could do this:
+
+```js
+{% raw %}<button onclick="someFunction()">Click me</button>
+
+<p id="intro"></p>
+
+<script>
+
+function someFunction() {
+    document.getElementById("intro").innerHTML = "{{ page.someContent }}";
+}
+</script>{% endraw %}
+```
+
+When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`.
+
+The key to remember is that Liquid renders when Jekyll builds your site. Liquid is not available at run-time in the browser when a user executes an event.
+
+## Note about using Liquid in YAML
+
+There's one more detail to remember: Liquid does not render when embedded in YAML files or front matter. (This isn't related to order of interpretation, but it's worth mentioning because it's a common question about element rendering.)
+
+For example, suppose you have a `highlight` tag in your `_data/mydata.yml` file:
+
+```
+{% raw %}myvalue: >
+  {% highlight javascript %}
+  console.log('alert');
+  {% endhighlight %}{% endraw %}
+```
+
+On a page, you try to insert the value:
+
+```
+{% raw %}{{ site.data.mydata.myvalue }}{% endraw %}
+```
+
+This would render only as a string rather than a code sample with syntax highlighting. To make the code render, consider using an include instead.

features/site_configuration.feature

@@ -44,9 +44,11 @@ Feature: Site configuration
     Given I have an "Rakefile" file that contains "I want to be excluded"
     And I have an "README" file that contains "I want to be excluded"
     And I have an "index.html" file that contains "I want to be included"
+    And I have a "Gemfile" file that contains "gem 'include-me'"
     And I have a configuration file with "exclude" set to "['Rakefile', 'README']"
     When I run jekyll build
     Then I should see "I want to be included" in "_site/index.html"
+    And the "_site/Gemfile" file should exist
     And the "_site/Rakefile" file should not exist
     And the "_site/README" file should not exist
 

lib/jekyll/configuration.rb

@@ -18,7 +18,8 @@ module Jekyll
       "safe"              => false,
       "include"           => [".htaccess"],
       "exclude"           => %w(
-        node_modules vendor/bundle/ vendor/cache/ vendor/gems/ vendor/ruby/
+        Gemfile Gemfile.lock node_modules vendor/bundle/ vendor/cache/ vendor/gems/
+        vendor/ruby/
       ),
       "keep_files"        => [".git", ".svn"],
       "encoding"          => "utf-8",

lib/jekyll/drops/static_file_drop.rb

@@ -0,0 +1,11 @@
+module Jekyll
+  module Drops
+    class StaticFileDrop < Drop
+      extend Forwardable
+      def_delegators :@obj, :name, :extname, :modified_time, :basename
+      def_delegator :@obj, :relative_path, :path
+      def_delegator :@obj, :data, :fallback_data
+      def_delegator :@obj, :type, :collection
+    end
+  end
+end

lib/jekyll/static_file.rb

@@ -28,6 +28,10 @@ module Jekyll
       @collection = collection
       @relative_path = File.join(*[@dir, @name].compact)
       @extname = File.extname(@name)
+
+      data.default_proc = proc do |_, key|
+        site.frontmatter_defaults.find(relative_path, type, key)
+      end
     end
     # rubocop: enable ParameterLists
 
@@ -96,13 +100,15 @@ module Jekyll
     end
 
     def to_liquid
-      {
-        "basename"      => File.basename(name, extname),
-        "name"          => name,
-        "extname"       => extname,
-        "modified_time" => modified_time,
-        "path"          => File.join("", relative_path),
-      }
+      @to_liquid ||= Drops::StaticFileDrop.new(self)
+    end
+
+    def data
+      @data ||= {}
+    end
+
+    def basename
+      File.basename(name, extname)
     end
 
     def placeholders

lib/site_template/_config.yml

@@ -29,6 +29,15 @@ markdown: kramdown
 theme: minima
 gems:
   - jekyll-feed
-exclude:
-  - Gemfile
-  - Gemfile.lock
+
+# Exclude from processing.
+# The following items will not be processed, by default. Create a custom list
+# to override the default setting.
+# exclude:
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/

test/test_configuration.rb

@@ -55,6 +55,8 @@ class TestConfiguration < JekyllUnitTest
 
     should "exclude ruby vendor directories" do
       exclude = Configuration.from({})["exclude"]
+      assert_includes exclude, "Gemfile"
+      assert_includes exclude, "Gemfile.lock"
       assert_includes exclude, "vendor/bundle/"
       assert_includes exclude, "vendor/cache/"
       assert_includes exclude, "vendor/gems/"

test/test_site_drop.rb

@@ -4,7 +4,7 @@ class TestSiteDrop < JekyllUnitTest
   context "a site drop" do
     setup do
       @site = fixture_site({
-        "collections" => ["thanksgiving"]
+        "collections" => ["thanksgiving"],
       })
       @site.process
       @drop = @site.to_liquid.site

test/test_static_file.rb

@@ -148,8 +148,9 @@ class TestStaticFile < JekyllUnitTest
         "extname"       => ".txt",
         "modified_time" => @static_file.modified_time,
         "path"          => "/static_file.txt",
+        "collection"    => nil,
       }
-      assert_equal expected, @static_file.to_liquid
+      assert_equal expected, @static_file.to_liquid.to_h
     end
   end
 end