From 2d0df85b93f767a12059a5fb0402d36e6e3c0b81 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:42:16 -0800 Subject: [PATCH 01/10] Add includes link to doc nav I created more advanced details about includes and created a new page for it instead of putting all the info on the templates page. See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. @jekyll/documentation @DirtyF --- docs/_data/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_data/docs.yml b/docs/_data/docs.yml index 4ff28ba2..cb24042e 100644 --- a/docs/_data/docs.yml +++ b/docs/_data/docs.yml @@ -19,6 +19,7 @@ - datafiles - assets - migrations + - includes - title: Customization docs: From 503420a9b45e36cbf718ddc0069dba0f64858fee Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:44:35 -0800 Subject: [PATCH 02/10] Added new includes.md topic to docs Added new includes.md topic. See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. @jekyll/documentation @DirtyF --- docs/_docs/includes.md | 175 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/_docs/includes.md diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md new file mode 100644 index 00000000..dceece77 --- /dev/null +++ b/docs/_docs/includes.md @@ -0,0 +1,175 @@ +--- +layout: docs +title: Includes +permalink: /docs/includes/ +--- + +The `include` tag allows you to include the content from another file stored in the `_includes` folder: + +```liquid +{% raw %}{% include footer.html %}{% endraw %} +``` + +Jekyll will look for the referenced file (in this case, `footer.html`) in the `_includes` directory at the root of your source directory and insert its contents. + +### Including files relative to another file + +You can choose to include file fragments relative to the current file by using the `include_relative` tag: + +```liquid +{% raw %}{% include_relative somedir/footer.html %}{% endraw %} +``` + +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 its subdirectories. + +Note that you cannot use the `../` syntax to specify an include location that refers to a higher-level directory. + +All the other capabilities of the `include` tag are available to the `include_relative` tag, +such as variables. + +### Using variables names for the include file + +The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's frontmatter like this: + +```yaml +--- +title: My page +my_variable: footer_company_a.html +--- +``` + +You could then reference that variable in your include: + +```liquid +{% raw %}{% include {{page.my_variable}} %}{% endraw %} +``` + +In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. + +### Passing parameters to includes + +You can also pass parameters to an include. For example, suppose you have a file called `note.html` in your `_includes` folder that contains this formatting: + +```liquid +{% raw %}{% endraw %} +``` + +The {% raw %}`{{include.content}}`{% endraw %} is a parameter gets populated when you call the include and specify a value for that parameter, like this: + +```liquid +{% raw %}{% include note.html content="This is my sample note." %} {% endraw %} +``` + +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. + +Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. + +For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: + +```html +
Jekyll logo
+This is the Jekyll logo
+``` + +You could templatize this content in your include and make each value available as a parameter, like this: + +```liquid +{% raw %}
{{include.caption}} +
{% endraw %} +``` + +This include contains 5 parameters: + +* `url` +* `max-width` +* `file` +* `alt` +* `caption` + +You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: + +```liquid +{% raw %}
{% if {{include.url}} %} +{% endif %}{% if {{include.url}} %}{% endif %} +{% if {{include.caption}} %}
{{include.caption}} +
{% endif %}
{% endraw %} +``` + +In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). + +Here's an example that passes all the parameters to this include (the include file is named `image.html`): + +```liquid +{% raw %}{% include image.html url="http://jekyllrb.com" +max-width="200px" file="logo.png" alt="Jekyll logo" +caption="This is the Jekyll logo." %} {% endraw %} +``` + +The result is the original HTML code shown earlier. + +You can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. + +However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) + +### Passing parameter variables to includes + +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) + +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} + +If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: + +```liquid +{% raw %}{% capture download_note %}The latest version of +{{site.product_name}} is now available.{% endcapture %}{% endraw %} +``` + +Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): + +```liquid +{% raw %}{% include note.html content=download_note %}{% endraw %} +``` + +### Passing references to YAML files as parameter values + +Instead of passing string variables to the include, you can pass a reference to a YAML data file stored in the `_data` folder. + +Here's an example. In the `_data` folder, suppose you have a YAML file called `profiles.yml`. Its content looks like this: + +```yaml +- name: John Doe + login_age: old + image: johndoe.jpg + +- name: Jane Doe + login_age: new + image: janedoe.jpg +``` + +In the `_includes` folder, assume you have a file called `spotlight.html` with this code: + +```liquid +{% raw %}{% for person in {{include.participants}} %} +{% if person.login_age == "new" %} +{{person.name}} +{% endif %} +{% endfor %}{% endraw %} +``` + +Now when you insert the `spotlight.html` include file, you can submit the YAML file as a parameter: + +``` +{% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} +``` + +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From 31de9ea484e996188a9407a416e236f7e0b4f2a6 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 18:28:27 -0800 Subject: [PATCH 03/10] made requested updates - made `{{ }}` formatting more readable by adding spacing. - added formatting to code samples to properly reflect line breaks for readability --- docs/_docs/includes.md | 57 ++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index dceece77..3a0b819d 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{page.my_variable}} %}{% endraw %} +{% raw %}{% include {{ page.my_variable }} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -55,35 +55,41 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The {% raw %}`{{include.content}}`{% endraw %} is a parameter gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{ include.content }}{% endraw %}` is a parameter gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: ```html -
Jekyll logo
-This is the Jekyll logo
+
+ + Jekyll logo +
This is the Jekyll logo
+
``` You could templatize this content in your include and make each value available as a parameter, like this: ```liquid -{% raw %}
{{include.caption}} -
{% endraw %} +{% raw %}
+ + {{ include.alt }} +
{{ include.caption }}
+
{% endraw %} ``` This include contains 5 parameters: @@ -97,15 +103,18 @@ This include contains 5 parameters: You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: ```liquid -{% raw %}
{% if {{include.url}} %} -{% endif %}{% if {{include.url}} %}{% endif %} -{% if {{include.caption}} %}
{{include.caption}} -
{% endif %}
{% endraw %} +{% raw %}
+ {% if {{ include.url }} %}{% endif %} + {{ include.alt }}{% if {{ include.url }} %}{% endif %} + {% if {{ include.caption }} %} +
{{ include.caption }}
+ {% endif %} +
{% endraw %} ``` -In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). +In this example, `{% raw %}if {{ include.url }}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). Here's an example that passes all the parameters to this include (the include file is named `image.html`): @@ -123,15 +132,15 @@ However, note that you should avoid using too many includes, as this will slow d ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{site.product_name}} is now available.{% endcapture %}{% endraw %} +{{ site.product_name }} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -159,9 +168,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{include.participants}} %} +{% raw %}{% for person in {{ include.participants }} %} {% if person.login_age == "new" %} -{{person.name}} +{{ person.name }} {% endif %} {% endfor %}{% endraw %} ``` @@ -172,4 +181,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From 488ec5489c1efc69547ad86e7d93feaf2a6d3c50 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 18:36:39 -0800 Subject: [PATCH 04/10] moved includes to appear after templates made update based on review. moved includes topic after templates in nav list. --- docs/_data/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_data/docs.yml b/docs/_data/docs.yml index cb24042e..bb9d3b14 100644 --- a/docs/_data/docs.yml +++ b/docs/_data/docs.yml @@ -19,11 +19,11 @@ - datafiles - assets - migrations - - includes - title: Customization docs: - templates + - includes - permalinks - pagination - plugins From f18363ea1383cb6b2791464c44cb06f7b4020212 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 27 Dec 2016 11:03:23 -0800 Subject: [PATCH 05/10] Updated to remove spacing from include variables It turns out Liquid throws an error when you write `{% if {{ include.url }} %}` instead of `{% if {{include.url}} %}`. I updated the examples here to omit the spacing. To avoid inconsistency, I just omitted the spacing from all curly braces. Also added a note explaining the issue and put the blame on Liquid. --- docs/_docs/includes.md | 46 ++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index 3a0b819d..1a60ce0d 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -32,7 +32,7 @@ such as variables. ### Using variables names for the include file -The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's frontmatter like this: +The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's front matter like this: ```yaml --- @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{ page.my_variable }} %}{% endraw %} +{% raw %}{% include {{page.my_variable}} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -56,17 +56,17 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The `{% raw %}{{ include.content }}{% endraw %}` is a parameter gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{include.content}}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. @@ -85,10 +85,10 @@ You could templatize this content in your include and make each value available ```liquid {% raw %}
- - {{ include.alt }} -
{{ include.caption }}
+ + {{include.alt}} +
{{include.caption}}
{% endraw %} ``` @@ -104,17 +104,17 @@ You could also use `if` tags to safeguard scenarios where either the parameter i ```liquid {% raw %}
- {% if {{ include.url }} %}{% endif %} - {{ include.alt }}{% if {{ include.url }} %}{% endif %} - {% if {{ include.caption }} %} -
{{ include.caption }}
+ {% if {{include.url}} %}{% endif %} + {{include.alt}}{% if {{include.url}} %}{% endif %} + {% if {{include.caption}} %} +
{{include.caption}}
{% endif %}
{% endraw %} ``` -In this example, `{% raw %}if {{ include.url }}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). +In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). Here's an example that passes all the parameters to this include (the include file is named `image.html`): @@ -130,17 +130,19 @@ You can create includes that act as templates for a variety of uses — inse However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) +Additionally, if you have a include variable inside an `if` statement, such as `{% raw %}{% if {{include.url}} %}{% endraw %}`, don't use spaces inside the curly braces. For example, avoid this syntax: `{% raw %}{% if {{ include.url }} %}{% endraw %}`. Liquid will consider this extra spacing an error. (Outside of `if` statements, the spacing for include variables doesn't matter.) + ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{ site.product_name }} is now available.{% endcapture %}{% endraw %} +{{site.product_name}} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -168,9 +170,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{ include.participants }} %} +{% raw %}{% for person in {{include.participants}} %} {% if person.login_age == "new" %} -{{ person.name }} +{{person.name}} {% endif %} {% endfor %}{% endraw %} ``` @@ -181,4 +183,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From 56ae6ed571aec6f10aefae44442d879261f31cc8 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 27 Dec 2016 21:39:56 -0800 Subject: [PATCH 06/10] Removed erroneous liquid code, added back spacing - removed erroneous liquid code with conditional include parameters - added back spacing in {{ }} tags --- docs/_docs/includes.md | 52 ++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 35 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index 1a60ce0d..94c56894 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{page.my_variable}} %}{% endraw %} +{% raw %}{% include {{ page.my_variable }} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -56,21 +56,21 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The `{% raw %}{{include.content}}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. -For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: +For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you might want to populate with an include: ```html
@@ -85,10 +85,10 @@ You could templatize this content in your include and make each value available ```liquid {% raw %}
- - {{include.alt}} -
{{include.caption}}
+ + {{ include.alt }} +
{{ include.caption }}
{% endraw %} ``` @@ -100,22 +100,6 @@ This include contains 5 parameters: * `alt` * `caption` -You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: - -```liquid -{% raw %}
- {% if {{include.url}} %}{% endif %} - {{include.alt}}{% if {{include.url}} %}{% endif %} - {% if {{include.caption}} %} -
{{include.caption}}
- {% endif %} -
{% endraw %} -``` - -In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). - Here's an example that passes all the parameters to this include (the include file is named `image.html`): ```liquid @@ -126,23 +110,21 @@ caption="This is the Jekyll logo." %} {% endraw %} The result is the original HTML code shown earlier. -You can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. +To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). -However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) - -Additionally, if you have a include variable inside an `if` statement, such as `{% raw %}{% if {{include.url}} %}{% endraw %}`, don't use spaces inside the curly braces. For example, avoid this syntax: `{% raw %}{% if {{ include.url }} %}{% endraw %}`. Liquid will consider this extra spacing an error. (Outside of `if` statements, the spacing for include variables doesn't matter.) +Overall, you can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{site.product_name}} is now available.{% endcapture %}{% endraw %} +{{ site.product_name }} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -170,9 +152,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{include.participants}} %} +{% raw %}{% for person in {{ include.participants }} %} {% if person.login_age == "new" %} -{{person.name}} +{{ person.name }} {% endif %} {% endfor %}{% endraw %} ``` @@ -183,4 +165,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include file, and the Liquid logic processes. The result will be `Jane Doe`. From 240ea135760d7a5943b1bd5aaaf68b19c9248e0e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:44:35 -0800 Subject: [PATCH 07/10] Added new includes.md topic to docs Added new includes.md topic. See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. @jekyll/documentation @DirtyF --- docs/_docs/includes.md | 175 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 docs/_docs/includes.md diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md new file mode 100644 index 00000000..dceece77 --- /dev/null +++ b/docs/_docs/includes.md @@ -0,0 +1,175 @@ +--- +layout: docs +title: Includes +permalink: /docs/includes/ +--- + +The `include` tag allows you to include the content from another file stored in the `_includes` folder: + +```liquid +{% raw %}{% include footer.html %}{% endraw %} +``` + +Jekyll will look for the referenced file (in this case, `footer.html`) in the `_includes` directory at the root of your source directory and insert its contents. + +### Including files relative to another file + +You can choose to include file fragments relative to the current file by using the `include_relative` tag: + +```liquid +{% raw %}{% include_relative somedir/footer.html %}{% endraw %} +``` + +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 its subdirectories. + +Note that you cannot use the `../` syntax to specify an include location that refers to a higher-level directory. + +All the other capabilities of the `include` tag are available to the `include_relative` tag, +such as variables. + +### Using variables names for the include file + +The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's frontmatter like this: + +```yaml +--- +title: My page +my_variable: footer_company_a.html +--- +``` + +You could then reference that variable in your include: + +```liquid +{% raw %}{% include {{page.my_variable}} %}{% endraw %} +``` + +In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. + +### Passing parameters to includes + +You can also pass parameters to an include. For example, suppose you have a file called `note.html` in your `_includes` folder that contains this formatting: + +```liquid +{% raw %}{% endraw %} +``` + +The {% raw %}`{{include.content}}`{% endraw %} is a parameter gets populated when you call the include and specify a value for that parameter, like this: + +```liquid +{% raw %}{% include note.html content="This is my sample note." %} {% endraw %} +``` + +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. + +Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. + +For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: + +```html +
Jekyll logo
+This is the Jekyll logo
+``` + +You could templatize this content in your include and make each value available as a parameter, like this: + +```liquid +{% raw %}
{{include.caption}} +
{% endraw %} +``` + +This include contains 5 parameters: + +* `url` +* `max-width` +* `file` +* `alt` +* `caption` + +You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: + +```liquid +{% raw %}
{% if {{include.url}} %} +{% endif %}{% if {{include.url}} %}{% endif %} +{% if {{include.caption}} %}
{{include.caption}} +
{% endif %}
{% endraw %} +``` + +In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). + +Here's an example that passes all the parameters to this include (the include file is named `image.html`): + +```liquid +{% raw %}{% include image.html url="http://jekyllrb.com" +max-width="200px" file="logo.png" alt="Jekyll logo" +caption="This is the Jekyll logo." %} {% endraw %} +``` + +The result is the original HTML code shown earlier. + +You can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. + +However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) + +### Passing parameter variables to includes + +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) + +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} + +If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: + +```liquid +{% raw %}{% capture download_note %}The latest version of +{{site.product_name}} is now available.{% endcapture %}{% endraw %} +``` + +Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): + +```liquid +{% raw %}{% include note.html content=download_note %}{% endraw %} +``` + +### Passing references to YAML files as parameter values + +Instead of passing string variables to the include, you can pass a reference to a YAML data file stored in the `_data` folder. + +Here's an example. In the `_data` folder, suppose you have a YAML file called `profiles.yml`. Its content looks like this: + +```yaml +- name: John Doe + login_age: old + image: johndoe.jpg + +- name: Jane Doe + login_age: new + image: janedoe.jpg +``` + +In the `_includes` folder, assume you have a file called `spotlight.html` with this code: + +```liquid +{% raw %}{% for person in {{include.participants}} %} +{% if person.login_age == "new" %} +{{person.name}} +{% endif %} +{% endfor %}{% endraw %} +``` + +Now when you insert the `spotlight.html` include file, you can submit the YAML file as a parameter: + +``` +{% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} +``` + +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From 8289b6131616dab2abfcc4925ea166d6e99af600 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 18:28:27 -0800 Subject: [PATCH 08/10] made requested updates - made `{{ }}` formatting more readable by adding spacing. - added formatting to code samples to properly reflect line breaks for readability --- docs/_docs/includes.md | 57 ++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index dceece77..3a0b819d 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{page.my_variable}} %}{% endraw %} +{% raw %}{% include {{ page.my_variable }} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -55,35 +55,41 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The {% raw %}`{{include.content}}`{% endraw %} is a parameter gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{ include.content }}{% endraw %}` is a parameter gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: ```html -
Jekyll logo
-This is the Jekyll logo
+
+ + Jekyll logo +
This is the Jekyll logo
+
``` You could templatize this content in your include and make each value available as a parameter, like this: ```liquid -{% raw %}
{{include.caption}} -
{% endraw %} +{% raw %}
+ + {{ include.alt }} +
{{ include.caption }}
+
{% endraw %} ``` This include contains 5 parameters: @@ -97,15 +103,18 @@ This include contains 5 parameters: You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: ```liquid -{% raw %}
{% if {{include.url}} %} -{% endif %}{% if {{include.url}} %}{% endif %} -{% if {{include.caption}} %}
{{include.caption}} -
{% endif %}
{% endraw %} +{% raw %}
+ {% if {{ include.url }} %}{% endif %} + {{ include.alt }}{% if {{ include.url }} %}{% endif %} + {% if {{ include.caption }} %} +
{{ include.caption }}
+ {% endif %} +
{% endraw %} ``` -In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). +In this example, `{% raw %}if {{ include.url }}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). Here's an example that passes all the parameters to this include (the include file is named `image.html`): @@ -123,15 +132,15 @@ However, note that you should avoid using too many includes, as this will slow d ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{site.product_name}} is now available.{% endcapture %}{% endraw %} +{{ site.product_name }} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -159,9 +168,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{include.participants}} %} +{% raw %}{% for person in {{ include.participants }} %} {% if person.login_age == "new" %} -{{person.name}} +{{ person.name }} {% endif %} {% endfor %}{% endraw %} ``` @@ -172,4 +181,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From 56a7038a7edd5141c76e4b295a7566ba5e2b1f03 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 27 Dec 2016 11:03:23 -0800 Subject: [PATCH 09/10] Updated to remove spacing from include variables It turns out Liquid throws an error when you write `{% if {{ include.url }} %}` instead of `{% if {{include.url}} %}`. I updated the examples here to omit the spacing. To avoid inconsistency, I just omitted the spacing from all curly braces. Also added a note explaining the issue and put the blame on Liquid. --- docs/_docs/includes.md | 46 ++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index 3a0b819d..1a60ce0d 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -32,7 +32,7 @@ such as variables. ### Using variables names for the include file -The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's frontmatter like this: +The name of the file you want to embed can be specified as a variable instead of an actual file name. For example, suppose you defined a variable in your page's front matter like this: ```yaml --- @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{ page.my_variable }} %}{% endraw %} +{% raw %}{% include {{page.my_variable}} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -56,17 +56,17 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The `{% raw %}{{ include.content }}{% endraw %}` is a parameter gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{include.content}}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. @@ -85,10 +85,10 @@ You could templatize this content in your include and make each value available ```liquid {% raw %}
- - {{ include.alt }} -
{{ include.caption }}
+ + {{include.alt}} +
{{include.caption}}
{% endraw %} ``` @@ -104,17 +104,17 @@ You could also use `if` tags to safeguard scenarios where either the parameter i ```liquid {% raw %}
- {% if {{ include.url }} %}{% endif %} - {{ include.alt }}{% if {{ include.url }} %}{% endif %} - {% if {{ include.caption }} %} -
{{ include.caption }}
+ {% if {{include.url}} %}{% endif %} + {{include.alt}}{% if {{include.url}} %}{% endif %} + {% if {{include.caption}} %} +
{{include.caption}}
{% endif %}
{% endraw %} ``` -In this example, `{% raw %}if {{ include.url }}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). +In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). Here's an example that passes all the parameters to this include (the include file is named `image.html`): @@ -130,17 +130,19 @@ You can create includes that act as templates for a variety of uses — inse However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) +Additionally, if you have a include variable inside an `if` statement, such as `{% raw %}{% if {{include.url}} %}{% endraw %}`, don't use spaces inside the curly braces. For example, avoid this syntax: `{% raw %}{% if {{ include.url }} %}{% endraw %}`. Liquid will consider this extra spacing an error. (Outside of `if` statements, the spacing for include variables doesn't matter.) + ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{ site.product_name }} is now available.{% endcapture %}{% endraw %} +{{site.product_name}} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -168,9 +170,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{ include.participants }} %} +{% raw %}{% for person in {{include.participants}} %} {% if person.login_age == "new" %} -{{ person.name }} +{{person.name}} {% endif %} {% endfor %}{% endraw %} ``` @@ -181,4 +183,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. From acff6cd269ea516ac8aaf4922f57c8f2be2367db Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 27 Dec 2016 21:39:56 -0800 Subject: [PATCH 10/10] Removed erroneous liquid code, added back spacing - removed erroneous liquid code with conditional include parameters - added back spacing in {{ }} tags --- docs/_docs/includes.md | 52 ++++++++++++++---------------------------- 1 file changed, 17 insertions(+), 35 deletions(-) diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index 1a60ce0d..94c56894 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -44,7 +44,7 @@ my_variable: footer_company_a.html You could then reference that variable in your include: ```liquid -{% raw %}{% include {{page.my_variable}} %}{% endraw %} +{% raw %}{% include {{ page.my_variable }} %}{% endraw %} ``` In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory. @@ -56,21 +56,21 @@ You can also pass parameters to an include. For example, suppose you have a file ```liquid {% raw %}{% endraw %} ``` -The `{% raw %}{{include.content}}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: +The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: ```liquid {% raw %}{% include note.html content="This is my sample note." %} {% endraw %} ``` -The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{include.content}}`{% endraw %} parameter. +The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter. Passing parameters to includes is especially helpful when you want to hide away complex formatting from your Markdown content. -For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you want to populate with an include: +For example, suppose you have a special image syntax with complex formatting, and you don't want your authors to remember the complex formatting. As a result, you decide to simplify the formatting by using an include with parameters. Here's an example of the special image syntax you might want to populate with an include: ```html
@@ -85,10 +85,10 @@ You could templatize this content in your include and make each value available ```liquid {% raw %}
- - {{include.alt}} -
{{include.caption}}
+ + {{ include.alt }} +
{{ include.caption }}
{% endraw %} ``` @@ -100,22 +100,6 @@ This include contains 5 parameters: * `alt` * `caption` -You could also use `if` tags to safeguard scenarios where either the parameter is optional or where the author doesn't include the parameter: - -```liquid -{% raw %}
- {% if {{include.url}} %}{% endif %} - {{include.alt}}{% if {{include.url}} %}{% endif %} - {% if {{include.caption}} %} -
{{include.caption}}
- {% endif %} -
{% endraw %} -``` - -In this example, `{% raw %}if {{include.url}}{% endraw %}` will include the `url` only if the `url` parameter is specified in the include. You could also create default values using [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). - Here's an example that passes all the parameters to this include (the include file is named `image.html`): ```liquid @@ -126,23 +110,21 @@ caption="This is the Jekyll logo." %} {% endraw %} The result is the original HTML code shown earlier. -You can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. +To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default). -However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) - -Additionally, if you have a include variable inside an `if` statement, such as `{% raw %}{% if {{include.url}} %}{% endraw %}`, don't use spaces inside the curly braces. For example, avoid this syntax: `{% raw %}{% if {{ include.url }} %}{% endraw %}`. Liquid will consider this extra spacing an error. (Outside of `if` statements, the spacing for include variables doesn't matter.) +Overall, you can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.) ### Passing parameter variables to includes -Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{site.product_name}}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) +Suppose the parameter you want to pass to the include is a variable rather than a string. For example, you might be using {% raw %}`{{ site.product_name }}`{% endraw %} to refer to every instance of your product rather than the actual hard-coded name. (In this case, your `_config.yml` file would have a key called `product_name` with a value of your product's name.) -The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{site.product_name}} is now available."`{% endraw %} +The string you pass to your include parameter can't contain curly braces. For example, you can't pass a parameter that contains this: {% raw %}`"The latest version of {{ site.product_name }} is now available."`{% endraw %} If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable: ```liquid {% raw %}{% capture download_note %}The latest version of -{{site.product_name}} is now available.{% endcapture %}{% endraw %} +{{ site.product_name }} is now available.{% endcapture %}{% endraw %} ``` Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable): @@ -170,9 +152,9 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p In the `_includes` folder, assume you have a file called `spotlight.html` with this code: ```liquid -{% raw %}{% for person in {{include.participants}} %} +{% raw %}{% for person in {{ include.participants }} %} {% if person.login_age == "new" %} -{{person.name}} +{{ person.name }} {% endif %} {% endfor %}{% endraw %} ``` @@ -183,4 +165,4 @@ Now when you insert the `spotlight.html` include file, you can submit the YAML f {% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %} ``` -In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{include.participants}}`{% endraw %} in the include, and the Liquid logic processes. The result will be `Jane Doe`. +In this instance, `site.data.profiles` gets inserted in place of {% raw %}`{{ include.participants }}`{% endraw %} in the include file, and the Liquid logic processes. The result will be `Jane Doe`.