New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation about order of interpretation #5834

Merged
merged 4 commits into from Feb 11, 2017

Conversation

Projects
None yet
7 participants
@tomjoht
Contributor

tomjoht commented Jan 30, 2017

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

Add documentation about order of interpretation
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

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Jan 30, 2017

Member

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.

Member

ashmaroli commented Jan 30, 2017

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.

Show outdated Hide outdated 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.

This comment has been minimized.

@pathawks

pathawks Jan 30, 2017

Member

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

@pathawks

pathawks Jan 30, 2017

Member

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

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

This comment has been minimized.

@pathawks

pathawks Jan 30, 2017

Member

TIL

@pathawks
Show outdated Hide outdated 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.

This comment has been minimized.

@pathawks

pathawks Jan 30, 2017

Member

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

pathawks Jan 30, 2017

Member

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"
    …
Show outdated Hide outdated 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.

This comment has been minimized.

@pathawks

pathawks Jan 30, 2017

Member

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

pathawks Jan 30, 2017

Member

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.

Show outdated Hide outdated docs/_tutorials/orderofinterpretation.md
```liquid
{% raw %}if page.type == "home" {
$("intro").addClass("bright");

This comment has been minimized.

@pathawks

pathawks Jan 30, 2017

Member

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

@pathawks

pathawks Jan 30, 2017

Member

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

@swizca

This comment has been minimized.

Show comment
Hide comment
@swizca

swizca Jan 30, 2017

swizca commented Jan 30, 2017

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Jan 30, 2017

Member

{{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

Member

DirtyF commented Jan 30, 2017

{{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

This comment has been minimized.

Show comment
Hide comment
@swizca

swizca Jan 30, 2017

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

swizca commented Jan 30, 2017

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

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Jan 30, 2017

Member

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

Member

ashmaroli commented Jan 30, 2017

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

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Jan 30, 2017

Contributor

I made the updates that you all suggested. Thanks! Submitting for re-review.

Contributor

tomjoht commented Jan 30, 2017

I made the updates that you all suggested. Thanks! Submitting for re-review.

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.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Feb 4, 2017

Contributor

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?

Contributor

tomjoht commented Feb 4, 2017

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

Show outdated Hide outdated 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.)

This comment has been minimized.

@DirtyF

DirtyF Feb 4, 2017

Member

s/ Liquid filter/Liquid variable

@DirtyF

DirtyF Feb 4, 2017

Member

s/ Liquid filter/Liquid variable

This comment has been minimized.

@ashmaroli

ashmaroli Feb 4, 2017

Member

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]


@ashmaroli

ashmaroli Feb 4, 2017

Member

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]


This comment has been minimized.

@tomjoht

tomjoht Feb 6, 2017

Contributor

good point. i like this extra specificity.

@tomjoht

tomjoht Feb 6, 2017

Contributor

good point. i like this extra specificity.

Show outdated Hide outdated 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.

This comment has been minimized.

@DirtyF

DirtyF Feb 4, 2017

Member

s/stem/step?

@DirtyF

DirtyF Feb 4, 2017

Member

s/stem/step?

This comment has been minimized.

@pathawks

pathawks Feb 4, 2017

Member

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

@pathawks

pathawks Feb 4, 2017

Member

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

Fixes based on latest review
Mostly I added more detail in the Liquid section.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Feb 6, 2017

Contributor

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?

Contributor

tomjoht commented Feb 6, 2017

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?

@DirtyF

DirtyF approved these changes Feb 6, 2017

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

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Feb 11, 2017

Member

Thank you!

@jekyllbot: merge +site

Member

parkr commented Feb 11, 2017

Thank you!

@jekyllbot: merge +site

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

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

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

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Feb 11, 2017

Member

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.

Member

parkr commented Feb 11, 2017

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

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Feb 11, 2017

Contributor

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.

Contributor

tomjoht commented Feb 11, 2017

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment