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:
```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 %}<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 %}
```
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
<figure><a href="http://jekyllrb.com"><img src="logo.png"
style="max-width: 200px;" alt="Jekyll logo" /><figcaption>
This is the Jekyll logo</figcaption></figure>
<figure>
<a href="http://jekyllrb.com">
<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:
```liquid
{% raw %}<figure><a href="{{include.url}}"><img src="{{include.file}}"
style="max-width: {{include.max-width}};"
alt="{{include.alt}}"/><figcaption>{{include.caption}}
</figcaption></figure>{% endraw %}
{% raw %}<figure>
<a href="{{ include.url }}">
<img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
alt="{{ include.alt }}"/>
<figcaption>{{ include.caption }}</figcaption>
</figure>{% 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 %}<figure>{% if {{include.url}} %}<a href="{{include.url}}">
{% endif %}<img src="{{include.file}}" {% if {{include.max-width}}
%} style="max-width: {{include.max-width}}" {% endif %}
alt="{{include.alt}}" />{% if {{include.url}} %}</a>{% endif %}
{% if {{include.caption}} %}<figcaption>{{include.caption}}
</figcaption>{% endif %}</figure>{% endraw %}
{% raw %}<figure>
{% if {{ include.url }} %}<a href="{{ include.url }}">{% endif %}
<img src="{{ include.file }}" {% if {{ include.max-width }} %}
style="max-width: {{ include.max-width }}" {% endif %}
alt="{{ include.alt }}" />{% if {{ include.url }} %}</a>{% endif %}
{% 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`):
@ -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`.