Add documentation about order of interpretation #5834

tomjoht · 2017-01-30T05:45:31Z

This tutorial defines Jekyll's "order of interpretation," as @swizca called it in #5808. 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/core

@swizca

This tutorial defines Jekyll's "order of interpretation," as @swizca called it in [#5808](#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

ashmaroli · 2017-01-30T12:25:58Z

Just did a rough read-through.. found a few occurrences of {{variable}} instead of {{ variable }}.

[Random comment]: You have cautioned the user to never mix javascript and liquid due the difference in their individual processing.. and that is true in the context of this tutorial, but not something that should never be done.
Just for knowledge purposes,
The jekyll-assets plugin processes all .liquid files with Jekyll context.
If you give it a style.css.liquid containing liquid variables, it'll be processed into a valid style.css, a script.js.liquid into a script.js. But yes, core Jekyll doesn't.

pathawks · 2017-01-30T12:36:33Z

docs/_tutorials/orderofinterpretation.md

+```
+{% 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.


Does “nothing render,” or does it render as the string “{{myvar}}?”

pathawks · 2017-01-30T12:38:53Z

docs/_tutorials/orderofinterpretation.md

+{% 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.


pathawks · 2017-01-30T12:42:40Z

docs/_tutorials/orderofinterpretation.md

+ }{% 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.


I'm confused. I don't see any Liquid in the given JavaScript. There is a way to make it work:

if {{ page.type | jsonify }} === "home" …

pathawks · 2017-01-30T12:44:23Z

docs/_tutorials/orderofinterpretation.md

+
+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.


I understand what you're trying to say, but perhaps some different language could be used. Mixing Liquid and JavaScript might be Expert Mode, but it's not impossible.

pathawks · 2017-01-30T12:46:24Z

docs/_tutorials/orderofinterpretation.md

+
+```liquid
+{% raw %}if page.type == "home" { 
+    $("intro").addClass("bright");


Let's leave jQuery out of this; confusing enough as is.

swizca · 2017-01-30T15:53:00Z

Just did a rough read-through.. found a few occurrences of `{{variable}}` instead of `{{ variable }}`.

Why is this a concern? (Link?)

The `jekyll-assets` plugin processes all `.liquid` files with Jekyll context.

This is without the presence of Front Matter?

DirtyF · 2017-01-30T16:02:05Z

{{variable}} instead of {{ variable }}
Why is this a concern? (Link?)

This is the convention used on the whole website, it's a bit more readable.
http://ben.balter.com/jekyll-style-guide/liquid-syntax/#general-syntax

swizca · 2017-01-30T16:08:26Z

This is the convention used on the whole website, it's a bit more readable.
http://ben.balter.com/jekyll-style-guide/liquid-syntax/#general-syntax

Thanks! [Indentation, style, readability, given the differing processors involved, is something I still haven't wrapped my head around / chased down to a coherent whole. (Yaml being unhappy with tabs, multiple processors reacting to lack/presence of extra spacing, code blocks, and so on.)]

ashmaroli · 2017-01-30T16:34:28Z

This is without the presence of Front Matter?

I haven't used the plugin myself but the plugin's README does caution the user from setting features.liquid to true

tomjoht · 2017-01-30T19:46:12Z

I made the updates that you all suggested. Thanks! Submitting for re-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.

tomjoht · 2017-02-04T04:47:34Z

I fixed the issues noted in the reviews. Resubmitting for approval.

Hey, just curious, but things seem extra quiet in this repo lately. Is everyone taking a break after the release, or battling with jekyll talk issues?

DirtyF

Some small typos

DirtyF · 2017-02-04T14:20:32Z

docs/_tutorials/orderofinterpretation.md

+
+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.)


s/ Liquid filter/Liquid variable

Instead of saying

(Anything in Jekyll with {% raw %}{{ }}{% endraw %} curly braces or {% raw %}{% %}{% endraw %} is usually a Liquid filter or tag.)

and generalising, I feel its better to inform what's what.. i.e. :

Identify Liquid by the presence of curly brackets / braces:

Liguid Tags: They start with a {% and end with a %}. e.g. {% raw %}, {% highlight %}, {% css -- %}, {% seo %}. Tags can define blocks or can be inline. Block-defining tags will additionally come with a corresponding end-tag
i.e {% endraw %}, {% endhighlight %}

Liquid Variables: They start and end with double-braces. e.g. {{ site.myvariable }} , {{ content }}

Liquid Filters: They start with a pipe character (|) and can only be used within Liquid Variables after the variable string. e.g relative_url filter in {{ "css/main.css" | relative_url }}

Learn more about Liquid by referring the official documentation [LINK]

good point. i like this extra specificity.

DirtyF · 2017-02-04T14:23:09Z

docs/_tutorials/orderofinterpretation.md

+
+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.


s/stem/step?

@DirtyF
These problems come from…?
These problems are rooted in…?

Mostly I added more detail in the Liquid section.

tomjoht · 2017-02-06T04:56:52Z

I made updates based on the latest review. Resubmitting for consideration.

On another note, any update about when we can push out this new tutorials section? Are you waiting on me for anything related to that?

parkr · 2017-02-11T02:16:57Z

Thank you!

@jekyllbot: merge +site

parkr · 2017-02-11T02:19:04Z

any update about when we can push out this new tutorials section? Are you waiting on me for anything related to that?

We can push it out anytime! We need: an index.html file to greet the users and it needs to be added to the collections Hash in docs/_config.yml.

tomjoht · 2017-02-11T02:32:31Z

PR 5698 needs to be pushed before this one. PR5698 contains all the edits around enabling the tutorials collection and navigation. After 5698 goes live, then I'll add another link in the nav for this topic. I have another tutorial I'm about to submit as well, so we'll soon have 3 tutorials in that new Tutorials nav.

jekyllbot assigned DirtyF and parkr Jan 30, 2017

DirtyF added do-not-merge documentation labels Jan 30, 2017

pathawks reviewed Jan 30, 2017

View reviewed changes

Made updates as suggested by reviewers

a7cba8a

updated based on review

4b325a6

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.

pathawks approved these changes Feb 4, 2017

View reviewed changes

DirtyF reviewed Feb 4, 2017

View reviewed changes

Fixes based on latest review

755cc6c

Mostly I added more detail in the Liquid section.

DirtyF approved these changes Feb 6, 2017

View reviewed changes

parkr removed the do-not-merge label Feb 11, 2017

jekyllbot merged commit 2c1991f into jekyll:master Feb 11, 2017

jekyllbot added the documentation label Feb 11, 2017

jekyllbot added a commit that referenced this pull request Feb 11, 2017

Update history to reflect merge of #5834 [ci skip]

98e19c3

jekyll locked and limited conversation to collaborators Jul 11, 2019

jekyllbot added the frozen-due-to-age label Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation about order of interpretation #5834

Add documentation about order of interpretation #5834

tomjoht commented Jan 30, 2017 •

edited by DirtyF

ashmaroli commented Jan 30, 2017 •

edited

pathawks Jan 30, 2017

pathawks Jan 30, 2017

pathawks Jan 30, 2017

pathawks Jan 30, 2017

pathawks Jan 30, 2017

swizca commented Jan 30, 2017 via email •

edited by DirtyF

DirtyF commented Jan 30, 2017

swizca commented Jan 30, 2017

ashmaroli commented Jan 30, 2017

tomjoht commented Jan 30, 2017

tomjoht commented Feb 4, 2017

DirtyF left a comment

DirtyF Feb 4, 2017

ashmaroli Feb 4, 2017 •

edited

tomjoht Feb 6, 2017

DirtyF Feb 4, 2017

pathawks Feb 4, 2017

tomjoht commented Feb 6, 2017

parkr commented Feb 11, 2017

parkr commented Feb 11, 2017

tomjoht commented Feb 11, 2017


		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.


		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.)


		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.

Add documentation about order of interpretation #5834

Add documentation about order of interpretation #5834

Conversation

tomjoht commented Jan 30, 2017 • edited by DirtyF

ashmaroli commented Jan 30, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

swizca commented Jan 30, 2017 via email • edited by DirtyF

DirtyF commented Jan 30, 2017

swizca commented Jan 30, 2017

ashmaroli commented Jan 30, 2017

tomjoht commented Jan 30, 2017

tomjoht commented Feb 4, 2017

DirtyF left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ashmaroli Feb 4, 2017 • edited

Choose a reason for hiding this comment

Identify Liquid by the presence of curly brackets / braces:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomjoht commented Feb 6, 2017

parkr commented Feb 11, 2017

parkr commented Feb 11, 2017

tomjoht commented Feb 11, 2017

tomjoht commented Jan 30, 2017 •

edited by DirtyF

ashmaroli commented Jan 30, 2017 •

edited

swizca commented Jan 30, 2017 via email •

edited by DirtyF

ashmaroli Feb 4, 2017 •

edited