From 8289b6131616dab2abfcc4925ea166d6e99af600 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 18:28:27 -0800 Subject: [PATCH] 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`.