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:

  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. 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"