From 8bacf01c1b49042d9aeb1a9b82824f46292545e5 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 29 Jan 2017 21:45:03 -0800 Subject: [PATCH 01/25] Add documentation about order of interpretation This tutorial defines Jekyll's "order of interpretation," as @swizca called it in [#5808](https://github.com/jekyll/jekyll/pull/5698). This tutorial makes it clear how Jekyll processes files as it renders the static HTML output. This order-of-interpretation info is important for troubleshooting and generally understanding Jekyll. It's important to know how Jekyll generates out the files, what rules it uses, what order it processes things, and so forth. (Note: Please process 5698 before this request, because 5698 includes the tutorial collection/navigation that this tutorial fits into. I also need to update this commit to add a link in the Tutorials nav to this topic, but I'm waiting for 5698 to be merged so that menu becomes available.) @jekyll/documentation @dirtyf --- docs/_tutorials/orderofinterpretation.md | 133 +++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 docs/_tutorials/orderofinterpretation.md diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md new file mode 100644 index 00000000..e4e003be --- /dev/null +++ b/docs/_tutorials/orderofinterpretation.md @@ -0,0 +1,133 @@ +--- +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 formatting in pages that contain [front matter]({% link _docs/frontmatter.md %}). All Liquid tags, such as `include`, `highlight`, or `assign` tags, are rendered. (Anything in Jekyll with `{% raw %}{{ }}{% endraw %}` curly braces or `{% raw %}{% %}{% endraw %}` is usually a Liquid filter or tag.) + +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 yield 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 stem 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. + +### Liquid tag in data reference not rendered + +In `_data/mydata.yml`, suppose you have this mapping: + +``` +{% raw %}somevalue: {{myvar}}{% endraw %} +``` + +On a page, you try to insert this value: + +``` +{% raw %}{{site.data.mydata.somevalue}}{% endraw %} +``` +Nothing renders because first the site variables populate, and then Liquid renders. When the site variables populate, the value for `{% raw %}{{site.data.mydata.somevalue}}{% endraw %}` is simply `{% raw %}{{myvar}}{% endraw %}`, which registers as a string and gets printed as a string. You can't use Liquid in data files. + +Similarly, 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 renders as a string for the same reasons described above. When the `site.data.mydata.myvalue` tag populates, the value gets stored as a string and printed to the page as a string. + +To make the code work, consider populating content from includes. + +### 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 HMTL formatting in includes inserted into HTML files. + +However, 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 with JavaScript, like this: + +```liquid +{% raw %}if page.type == "home" { + $("intro").addClass("bright"); +elsif page.type == "normal" { + $("intro").addClass("muted"); + }{% endraw %} +``` + +The Liquid renders long before the page gets converted to HTML. So when JavaScript executes in the browser, the Liquid is no longer present. + +You can never mix Liquid with JavaScript because Liquid processes when the site builds. In contrast, JavaScript processes in the browser when a user interacts with your site. + +To make the code work, don't mix Liquid with JavaScript. If you need the code to execute in real-time in the browser, use JavaScript. From a7cba8a8a6686af2c8395bd627e2e8a2a2819a5e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 30 Jan 2017 11:45:24 -0800 Subject: [PATCH 02/25] Made updates as suggested by reviewers --- docs/_tutorials/orderofinterpretation.md | 59 ++++++++++++++++-------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md index e4e003be..bf3614a1 100644 --- a/docs/_tutorials/orderofinterpretation.md +++ b/docs/_tutorials/orderofinterpretation.md @@ -20,11 +20,11 @@ Jekyll converts your site in the following order: 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. +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 yield problems +## 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. @@ -41,7 +41,7 @@ In your layout file (`_layouts/default.html`), suppose you have a variable assig On a page that uses the layout, you reference that variable: ``` -{% raw %}{{myvar}}{% endraw %} +{% 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. @@ -53,15 +53,16 @@ To make the code work, you could put the variable assignment into the page's fro In `_data/mydata.yml`, suppose you have this mapping: ``` -{% raw %}somevalue: {{myvar}}{% endraw %} +{% raw %}somevalue: {{ myvar }}{% endraw %} ``` On a page, you try to insert this value: ``` -{% raw %}{{site.data.mydata.somevalue}}{% endraw %} +{% raw %}{{ site.data.mydata.somevalue }}{% endraw %} ``` -Nothing renders because first the site variables populate, and then Liquid renders. When the site variables populate, the value for `{% raw %}{{site.data.mydata.somevalue}}{% endraw %}` is simply `{% raw %}{{myvar}}{% endraw %}`, which registers as a string and gets printed as a string. You can't use Liquid in data files. + +This renders as a string (`{% raw %}"{{ site.data.mydata.somevalue }}{% endraw %}"` rather than the variable's value. This is because first the site variables populate, and then Liquid renders. When the site variables populate, the value for `{% raw %}{{ site.data.mydata.somevalue }}{% endraw %}` is simply `{% raw %}{{ myvar }}{% endraw %}`, which registers as a string. You can't use Liquid in data files. Similarly, suppose you have a `highlight` tag in your `_data/mydata.yml` file: @@ -75,7 +76,7 @@ Similarly, suppose you have a `highlight` tag in your `_data/mydata.yml` file: On a page, you try to insert the value: ``` -{% raw %}{{site.data.mydata.myvalue}}{% endraw %} +{% raw %}{{ site.data.mydata.myvalue }}{% endraw %} ``` This renders as a string for the same reasons described above. When the `site.data.mydata.myvalue` tag populates, the value gets stored as a string and printed to the page as a string. @@ -102,9 +103,9 @@ The Markdown is not processed because first the Liquid (`include` tag) gets proc 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 HMTL formatting in includes inserted into HTML files. +To make the code work, use HMTL formatting in includes that are inserted into HTML files. -However, note that `highlight` tags don't require Markdown to process. Suppose your include contains the following: +Note that `highlight` tags don't require Markdown to process. Suppose your include contains the following: ```liquid {% raw %}{% highlight javascript %} @@ -116,18 +117,38 @@ The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments ### Liquid mixed with JavaScript isn't rendered -Suppose you try to mix Liquid with JavaScript, like this: +Suppose you try to mix Liquid's `assign` tag with JavaScript, like this: -```liquid -{% raw %}if page.type == "home" { - $("intro").addClass("bright"); -elsif page.type == "normal" { - $("intro").addClass("muted"); - }{% endraw %} +```javascript +{% raw %} + +

+ +{% endraw %} ``` -The Liquid renders long before the page gets converted to HTML. So when JavaScript executes in the browser, the Liquid is no longer present. +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 page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything. -You can never mix Liquid with JavaScript because Liquid processes when the site builds. In contrast, JavaScript processes in the browser when a user interacts with your site. +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: -To make the code work, don't mix Liquid with JavaScript. If you need the code to execute in real-time in the browser, use JavaScript. +```js +{% raw %} + +

+ +{% 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. From 384be58b5e7e0b57433c47f6cd3de15eaf6ce612 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Tue, 31 Jan 2017 08:40:06 +0530 Subject: [PATCH 03/25] add missing comma --- test/test_site_drop.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/test_site_drop.rb b/test/test_site_drop.rb index 6175bbb8..b836c70d 100644 --- a/test/test_site_drop.rb +++ b/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 From 875486e8ae8ab5d18ca1c744eb3c8b7618065460 Mon Sep 17 00:00:00 2001 From: Nate Date: Mon, 30 Jan 2017 22:13:05 -0800 Subject: [PATCH 04/25] Add Termux section on troubleshooting --- docs/_docs/troubleshooting.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/_docs/troubleshooting.md b/docs/_docs/troubleshooting.md index d5f29671..8fb66942 100644 --- a/docs/_docs/troubleshooting.md +++ b/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 From 78a4f207449e323e77f67036eab504bea7b9d9cb Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Tue, 31 Jan 2017 03:50:10 -0500 Subject: [PATCH 05/25] Update history to reflect merge of #5835 [ci skip] --- History.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/History.markdown b/History.markdown index 2958d74e..252b41b4 100644 --- a/History.markdown +++ b/History.markdown @@ -8,6 +8,10 @@ * Install troubleshooting on Ubuntu (#5817) +### Development Fixes + + * [Rubocop] add missing comma (#5835) + ## 3.4.0 / 2016-01-27 ### Minor Enhancements From e0109633ded51bc5cbd31c114e751418f33855d8 Mon Sep 17 00:00:00 2001 From: Alfred Myers Date: Tue, 31 Jan 2017 13:05:26 -0200 Subject: [PATCH 06/25] Corrected date for version 3.4.0 Year should probably be 2017 instead of 2016 --- History.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/History.markdown b/History.markdown index 252b41b4..194b4a70 100644 --- a/History.markdown +++ b/History.markdown @@ -12,7 +12,7 @@ * [Rubocop] add missing comma (#5835) -## 3.4.0 / 2016-01-27 +## 3.4.0 / 2017-01-27 ### Minor Enhancements From 1457359ce500d734cd22349bc603077f9a76acff Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Tue, 31 Jan 2017 10:10:36 -0500 Subject: [PATCH 07/25] Update history to reflect merge of #5842 [ci skip] --- History.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/History.markdown b/History.markdown index 194b4a70..71e56083 100644 --- a/History.markdown +++ b/History.markdown @@ -12,6 +12,10 @@ * [Rubocop] add missing comma (#5835) +### Site Enhancements + + * Corrected date for version 3.4.0 (#5842) + ## 3.4.0 / 2017-01-27 ### Minor Enhancements From 0c59ac3d299ab498ff535c4de83253d9034c0ffa Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Tue, 31 Jan 2017 10:12:47 -0500 Subject: [PATCH 08/25] Update history to reflect merge of #5837 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 71e56083..3d0d01d6 100644 --- a/History.markdown +++ b/History.markdown @@ -7,6 +7,7 @@ ### Documentation * Install troubleshooting on Ubuntu (#5817) + * Add Termux section on troubleshooting (#5837) ### Development Fixes From 4b325a65afde21830b026ee978c847ac4c2c3b5b Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Fri, 3 Feb 2017 20:46:05 -0800 Subject: [PATCH 09/25] updated based on review I moved the section about liquid and yaml to the end and shortened it. i also clarified that isn't an order-of-interpretation issue why liquid doesn't render in yaml. I also fixed the type with HMTL. --- docs/_tutorials/orderofinterpretation.md | 60 +++++++++--------------- 1 file changed, 23 insertions(+), 37 deletions(-) diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md index bf3614a1..8ffb9d7e 100644 --- a/docs/_tutorials/orderofinterpretation.md +++ b/docs/_tutorials/orderofinterpretation.md @@ -48,41 +48,6 @@ The variable won't render because the page's order of interpretation is to rende To make the code work, you could put the variable assignment into the page's front matter. -### Liquid tag in data reference not rendered - -In `_data/mydata.yml`, suppose you have this mapping: - -``` -{% raw %}somevalue: {{ myvar }}{% endraw %} -``` - -On a page, you try to insert this value: - -``` -{% raw %}{{ site.data.mydata.somevalue }}{% endraw %} -``` - -This renders as a string (`{% raw %}"{{ site.data.mydata.somevalue }}{% endraw %}"` rather than the variable's value. This is because first the site variables populate, and then Liquid renders. When the site variables populate, the value for `{% raw %}{{ site.data.mydata.somevalue }}{% endraw %}` is simply `{% raw %}{{ myvar }}{% endraw %}`, which registers as a string. You can't use Liquid in data files. - -Similarly, 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 renders as a string for the same reasons described above. When the `site.data.mydata.myvalue` tag populates, the value gets stored as a string and printed to the page as a string. - -To make the code work, consider populating content from includes. - ### 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: @@ -103,7 +68,7 @@ The Markdown is not processed because first the Liquid (`include` tag) gets proc 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 HMTL formatting in includes that are inserted into HTML 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: @@ -132,7 +97,7 @@ function someFunction() { {% 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 page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything. +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: @@ -152,3 +117,24 @@ function someFunction() { 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 as a string rather than a code sample with syntax highlighting. To make the code render, you might use an include instead. From 7e45610379cf5419ceba3c8f9532eca25ee405bd Mon Sep 17 00:00:00 2001 From: Colin Date: Sat, 4 Feb 2017 15:52:42 +0000 Subject: [PATCH 10/25] Add the correct year to the 3.4.0 release date --- docs/_docs/history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/history.md b/docs/_docs/history.md index 2ddaf67a..7d96660a 100644 --- a/docs/_docs/history.md +++ b/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 From 20d2eb2709b9fda243a955d365fbb911cd0b51f6 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Sat, 4 Feb 2017 12:30:28 -0500 Subject: [PATCH 11/25] Update history to reflect merge of #5858 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 3d0d01d6..abf9b5f2 100644 --- a/History.markdown +++ b/History.markdown @@ -16,6 +16,7 @@ ### Site Enhancements * Corrected date for version 3.4.0 (#5842) + * Add the correct year to the 3.4.0 release date (#5858) ## 3.4.0 / 2017-01-27 From 4e40593a53e51c9f1e2ce567677bc1803bbd4829 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sun, 5 Feb 2017 01:26:41 +0530 Subject: [PATCH 12/25] exclude Gemfile and its lockfile by default --- lib/jekyll/configuration.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/jekyll/configuration.rb b/lib/jekyll/configuration.rb index 27e245e4..b4bf7c5a 100644 --- a/lib/jekyll/configuration.rb +++ b/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", From 6316856773a8c41d16c887e2df82ec8735f3890b Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sun, 5 Feb 2017 01:28:43 +0530 Subject: [PATCH 13/25] comment out 'exclude:' in config file --- lib/site_template/_config.yml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/lib/site_template/_config.yml b/lib/site_template/_config.yml index f5df9830..aa255a64 100644 --- a/lib/site_template/_config.yml +++ b/lib/site_template/_config.yml @@ -29,6 +29,17 @@ markdown: kramdown theme: minima gems: - jekyll-feed -exclude: - - Gemfile - - Gemfile.lock + +# Exclude from processing. +# The items below are excluded by default, to customize the list, uncomment the +# lines below and simply add to the list. Items removed will **not** be excluded +# from processing. +# +# exclude: +# - Gemfile +# - Gemfile.lock +# - node_modules +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ From 2813b9c03985e2c4bd7c1f74b246d5432cb41bf0 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sun, 5 Feb 2017 01:49:38 +0530 Subject: [PATCH 14/25] test exclusion of Gemfile --- test/test_configuration.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/test/test_configuration.rb b/test/test_configuration.rb index febc0cbe..9602c5c3 100644 --- a/test/test_configuration.rb +++ b/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/" From eb36ea095fb948ad21a820ba35fe145a43cbf352 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sun, 5 Feb 2017 01:56:49 +0530 Subject: [PATCH 15/25] test overriding default excludes --- features/site_configuration.feature | 2 ++ 1 file changed, 2 insertions(+) diff --git a/features/site_configuration.feature b/features/site_configuration.feature index 2d00f9b7..3aace794 100644 --- a/features/site_configuration.feature +++ b/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 From 3745b2456409882ba81f1c2e7cd6c4f868175f3b Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Sun, 5 Feb 2017 07:55:26 +0530 Subject: [PATCH 16/25] update comment for `exclude` array --- lib/site_template/_config.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/lib/site_template/_config.yml b/lib/site_template/_config.yml index aa255a64..436d5999 100644 --- a/lib/site_template/_config.yml +++ b/lib/site_template/_config.yml @@ -31,10 +31,8 @@ gems: - jekyll-feed # Exclude from processing. -# The items below are excluded by default, to customize the list, uncomment the -# lines below and simply add to the list. Items removed will **not** be excluded -# from processing. -# +# The following items will not be processed, by default. Create a custom list +# to override the default setting. # exclude: # - Gemfile # - Gemfile.lock From 755cc6c137dedefe7a070fdf03f427e102b5e866 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 5 Feb 2017 20:55:16 -0800 Subject: [PATCH 17/25] Fixes based on latest review Mostly I added more detail in the Liquid section. --- docs/_tutorials/orderofinterpretation.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md index 8ffb9d7e..1146c636 100644 --- a/docs/_tutorials/orderofinterpretation.md +++ b/docs/_tutorials/orderofinterpretation.md @@ -16,7 +16,10 @@ 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 formatting in pages that contain [front matter]({% link _docs/frontmatter.md %}). All Liquid tags, such as `include`, `highlight`, or `assign` tags, are rendered. (Anything in Jekyll with `{% raw %}{{ }}{% endraw %}` curly braces or `{% raw %}{% %}{% endraw %}` is usually a Liquid filter or tag.) +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. @@ -28,7 +31,7 @@ Jekyll converts your site in the following order: 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 stem from misunderstanding the order of interpretation and can be easily fixed. +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 @@ -137,4 +140,4 @@ On a page, you try to insert the value: {% raw %}{{ site.data.mydata.myvalue }}{% endraw %} ``` -This would render as a string rather than a code sample with syntax highlighting. To make the code render, you might use an include instead. +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. From 229769e249bc9a6703fda4a9af061cd639d1ca75 Mon Sep 17 00:00:00 2001 From: Ben Balter Date: Wed, 8 Feb 2017 17:44:47 -0500 Subject: [PATCH 18/25] add StaticFileDrop --- lib/jekyll/drops/static_file_drop.rb | 11 +++++++++++ lib/jekyll/static_file.rb | 20 +++++++++++++------- test/test_static_file.rb | 3 ++- 3 files changed, 26 insertions(+), 8 deletions(-) create mode 100644 lib/jekyll/drops/static_file_drop.rb diff --git a/lib/jekyll/drops/static_file_drop.rb b/lib/jekyll/drops/static_file_drop.rb new file mode 100644 index 00000000..e0af2f09 --- /dev/null +++ b/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 diff --git a/lib/jekyll/static_file.rb b/lib/jekyll/static_file.rb index 53b945d4..beea9ddf 100644 --- a/lib/jekyll/static_file.rb +++ b/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 diff --git a/test/test_static_file.rb b/test/test_static_file.rb index 114885db..b2299ae2 100644 --- a/test/test_static_file.rb +++ b/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 From 1d44be54216fc1dddf698a630ea4e5f7c0577bca Mon Sep 17 00:00:00 2001 From: Marcelo Canina Date: Fri, 10 Feb 2017 12:34:16 -0300 Subject: [PATCH 19/25] fix ial css classes in theme doc --- docs/_docs/themes.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/_docs/themes.md b/docs/_docs/themes.md index 551d9340..4db8d404 100644 --- a/docs/_docs/themes.md +++ b/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 From bdf594317b25899c4d9856e5d40e0c944363f48b Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Fri, 10 Feb 2017 14:26:16 -0500 Subject: [PATCH 20/25] Update history to reflect merge of #5876 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index abf9b5f2..33b3a5f8 100644 --- a/History.markdown +++ b/History.markdown @@ -8,6 +8,7 @@ * Install troubleshooting on Ubuntu (#5817) * Add Termux section on troubleshooting (#5837) + * fix ial css classes in theme doc (#5876) ### Development Fixes From 7b58bcfc9e0822649f4ea26843856ef46e801dad Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Fri, 10 Feb 2017 21:08:50 -0500 Subject: [PATCH 21/25] Update history to reflect merge of #5871 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 33b3a5f8..7d2c32b3 100644 --- a/History.markdown +++ b/History.markdown @@ -3,6 +3,7 @@ ### Minor Enhancements * Upgrade to Liquid v4 (#4362) + * Convert StaticFile liquid representation to a Drop & add front matter defaults support to StaticFiles (#5871) ### Documentation From bcebf58cbd1181ca73b05dac797c59a5d80d6e40 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Fri, 10 Feb 2017 21:10:11 -0500 Subject: [PATCH 22/25] Update history to reflect merge of #5860 [ci skip] --- History.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/History.markdown b/History.markdown index 7d2c32b3..8ef746b9 100644 --- a/History.markdown +++ b/History.markdown @@ -20,6 +20,10 @@ * Corrected date for version 3.4.0 (#5842) * Add the correct year to the 3.4.0 release date (#5858) +### Bug Fixes + + * Exclude Gemfile by default (#5860) + ## 3.4.0 / 2017-01-27 ### Minor Enhancements From ec234a4ef89629f40b3bb826f41948303a70a400 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 10 Feb 2017 21:05:32 -0500 Subject: [PATCH 23/25] Bump Ruby 2.1 testing up to Ruby 2.1.10 --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 66c85eaa..3a6ef68b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,7 +7,7 @@ sudo: false rvm: - &ruby1 2.3.3 - &ruby2 2.2.6 - - &ruby3 2.1.9 + - &ruby3 2.1.10 - &jruby jruby-9.1.7.0 matrix: From 23808c2ae64638f79e1cb2b51936827e98f70880 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Fri, 10 Feb 2017 21:16:25 -0500 Subject: [PATCH 24/25] Fix missing trailing comma to alleviate fmt errors Offenses: test/test_static_file.rb:151:9: C: [Corrected] Style/TrailingCommaInLiteral: Put a comma after the last item of a multiline hash. "collection" => nil ^^^^^^^^^^^^^^^^^^^^^^ --- test/test_static_file.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/test_static_file.rb b/test/test_static_file.rb index b2299ae2..1603420a 100644 --- a/test/test_static_file.rb +++ b/test/test_static_file.rb @@ -148,7 +148,7 @@ class TestStaticFile < JekyllUnitTest "extname" => ".txt", "modified_time" => @static_file.modified_time, "path" => "/static_file.txt", - "collection" => nil + "collection" => nil, } assert_equal expected, @static_file.to_liquid.to_h end From 98e19c3cf5122582a8d2b5ecaad805a7902f2e53 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Fri, 10 Feb 2017 21:16:58 -0500 Subject: [PATCH 25/25] Update history to reflect merge of #5834 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 8ef746b9..f6fb2e3a 100644 --- a/History.markdown +++ b/History.markdown @@ -19,6 +19,7 @@ * 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