Includes
What are Includes?
Includes allow you to specify content to be inserted into your project by typing a shorter substitute. It's useful for adding things like long boilerplate content that you may want to add many times, but that you don't want to copy and paste each time.
Using Includes In Your Project
There are two types of includes that you can use with Atlas: basic includes, and includes with variables.
Basic Includes
The simplest include inserts HTML in its place. This can be useful for boilerplate content that is tiresome to type over and over.
Syntax
The syntax for a basic include is as follows:
{% include 'x' %}
Instead of typing x, type the name of the include you wish to use. The important parts of the above syntax are:
- Empty lines above and below the include
- Starting with
{% include
and ending with%}
- Surrounding the name of the include with quote marks.
Example
In this example we have an include named oreillyaddress that inserts O'Reilly Media's mailing address.
Typing the following into a file:
this is a sentence I wrote {% include 'oreillyaddress' %} this is another sentence
Will result in the following:
<p>this is a sentence I wrote</p> <p>O'Reilly Media, Inc.<br/> 1005 Gravenstein Hwy N<br/> Sebastopol, CA 95472</p> <p>this is another sentence</p>
Includes with Variables
Includes can also use variables to create dynamic content, such as embedding a video from Youtube.
Syntax
The syntax for an include with a variable is as follows:
{% include 'x' with 'y' %}
As in the Basic Include Syntax, replace x with the name of the include. And replace y with the value you wish to pass to the include. Be sure to keep the quote marks.
- Empty lines above and below the include
- Starting with
{% include
and ending with%}
- Surrounding the name of the include with quote marks.
- After the name of the include type
with
- After
with
type the value of the variable to pass to the include, surrounded in quotes.
Example
Atlas has a 'youtube' include that embeds a video for you when you give it the id of a video. Typing the following into a file:
this is a sentence I wrote {% include 'youtube' with 'txqiwrbYGrs' %} this is another sentence I wrote
Will result in the following:
<p>this is a sentence I wrote</p> <iframe width="420" height="315" src="//www.youtube.com/embed/txqiwrbYGrs" frameborder="0" allowfullscreen></iframe> <p>this is another sentence</p>
Writing Your Own Includes
To write your own include, follow these steps:
- Create a folder in your project at the top level named
includes
. - Inside the new
includes
folder, create a file with a name following the format:_something.liquid
. That is, create a file that starts with an underscore (_
) and then the name of the include as you'd like to use it, no spaces. And finally, use the extension.liquid
. - In the file you created,
includes/_something.liquid
, you can write a template with a variable matching the name of the file. So if your file is named_something.liquid
, the following would be a variable in that file:{{ something }}
Disabling Includes and Templating
If you would like to prevent '{{', '{%', '%}' and '}}' from triggering template calls, you can include the following in the atlas.json
file:
"templating" : "false"