dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

made requested updates 

- made `{{ }}` formatting more readable by adding spacing. 
- added formatting to code samples to properly reflect line breaks for readability
This commit is contained in:
Tom Johnson 2016-12-26 18:28:27 -08:00 committed by Frank Taillandier
parent 240ea13576
commit 8289b61316
1 changed files with 33 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/_docs/includes.md
View File

@ -44,7 +44,7 @@ my_variable: footer_company_a.html
You could then reference that variable in your include: You could then reference that variable in your include:
```liquid ```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. 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 ```liquid
{% raw %}<div markdown="span" class="alert alert-info" role="alert"> {% raw %}<div markdown="span" class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i> <b>Note:</b> {{include.content}} <i class="fa fa-info-circle"></i> <b>Note:</b>
{{ include.content }}
</div>{% endraw %} </div>{% 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 ```liquid
{% raw %}{% include note.html content="This is my sample note." %} {% endraw %} {% 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. 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 want to populate with an include:
```html ```html
<figure><a href="http://jekyllrb.com"><img src="logo.png" <figure>
style="max-width: 200px;" alt="Jekyll logo" /><figcaption> <a href="http://jekyllrb.com">
This is the Jekyll logo</figcaption></figure> <img src="logo.png" style="max-width: 200px;"
alt="Jekyll logo" />
<figcaption>This is the Jekyll logo</figcaption>
</figure>
``` ```
You could templatize this content in your include and make each value available as a parameter, like this: You could templatize this content in your include and make each value available as a parameter, like this:
```liquid ```liquid
{% raw %}<figure><a href="{{include.url}}"><img src="{{include.file}}" {% raw %}<figure>
style="max-width: {{include.max-width}};" <a href="{{ include.url }}">
alt="{{include.alt}}"/><figcaption>{{include.caption}} <img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
</figcaption></figure>{% endraw %} alt="{{ include.alt }}"/>
<figcaption>{{ include.caption }}</figcaption>
</figure>{% endraw %}
``` ```
This include contains 5 parameters: 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: 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 ```liquid
{% raw %}<figure>{% if {{include.url}} %}<a href="{{include.url}}"> {% raw %}<figure>
{% endif %}<img src="{{include.file}}" {% if {{include.max-width}} {% if {{ include.url }} %}<a href="{{ include.url }}">{% endif %}
%} style="max-width: {{include.max-width}}" {% endif %} <img src="{{ include.file }}" {% if {{ include.max-width }} %}
alt="{{include.alt}}" />{% if {{include.url}} %}</a>{% endif %} style="max-width: {{ include.max-width }}" {% endif %}
{% if {{include.caption}} %}<figcaption>{{include.caption}} alt="{{ include.alt }}" />{% if {{ include.url }} %}</a>{% endif %}
</figcaption>{% endif %}</figure>{% endraw %} {% if {{ include.caption }} %}
<figcaption>{{ include.caption }}</figcaption>
{% endif %}
</figure>{% 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`): 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 ### 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: 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 ```liquid
{% raw %}{% capture download_note %}The latest version of {% 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): 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: In the `_includes` folder, assume you have a file called `spotlight.html` with this code:
```liquid ```liquid
{% raw %}{% for person in {{include.participants}} %} {% raw %}{% for person in {{ include.participants }} %}
{% if person.login_age == "new" %} {% if person.login_age == "new" %}
{{person.name}} {{ person.name }}
{% endif %} {% endif %}
{% endfor %}{% endraw %} {% 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 %} {% 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`.