Chapter 11. Includes

What are Includes?

Using Includes In Your Project

There are a few includes built in to Atlas. These includes are documented here. Let’s go over using two different includes.

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:

  1. Create a folder in your project at the top level named includes.
  2. 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.
  3. Open the file you created, includes/_something.liquid, you can write a template here with a variable matching the name of the file. So if your file is named _something.liquid then 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"