Template Tags

Template tags are a powerful way to create markup or variables. We’ve taken the most common things that we use in building our sites, and bundled them into easy-to-use, customizable tags.

assign

Assign any variable using standard = assignment.

{% assign name = 'Bob Johnson' %}
{% assign test = true %}

capture

Combine the output of several strings into a single variable. The capture tag will not output any of its contents to the screen.

{% capture classname %}{{ item.title | downcase }}-{{ item.id }}-color{% endcapture %}
<span class="{{ classname }}>{{ item.title }}</span>

comment

Comment simply deletes any of the markup or items inside of its start and end tags, and never outputs it to the screen.

{% comment %} This will never be seen. {% endcomment %}

A simple way to display a copyright line starting from a current date.

Syntax: copyright year[, text:‘Copyrighted Material’]

Assuming it is 2009:
{% copyright 2009 %} # => Copyright &copy; 2009
{% copyright 2004 %} # => Copyright &copy 2004 - 2009
{% copyright 2004, text:'My Copyright' %} # => My Copyright 2004 - 2009

cycle

Cycles through a list of items, restarting when it reaches the end.

{% cycle 'one', 'two', 'three' %} # => one
{% cycle 'one', 'two', 'three' %} # => two
{% cycle 'one', 'two', 'three' %} # => three
{% cycle 'one', 'two', 'three' %} # => one

You can also have multiple cycles going on at once, if you need.

{% cycle 'group 1': 'one', 'two', 'three' %} # => one
{% cycle 'group 2': 'one', 'two', 'three' %} # => one
{% cycle 'group 1': 'one', 'two', 'three' %} # => two
{% cycle 'group 2': 'one', 'two', 'three' %} # => two

feed

The feed tag will place you in the context of a particular data feed, and assign that feed data to the feed variable. You can then use and iterate over any data pulled from that feed.

Syntax: feed ‘feed_id’

{% feed '478fa87fa009890ds00a890a' %}
  {{ feed.title }}
{% endfeed %}

For more information, read our page describing how data feeds work.

include

Include an include file from your theme in a template or another include file.

{% include 'header' %}

You can also send particular data to an include, if you’d like to reuse the code, but for a different object each time. To send an object along with an include, pass it after the include statement using for, as shown.

{% include 'portfolio' for porfolio_object %}

You will then have access to portfolio_object inside the portfolio include using the variable named after the include, or in this case portfolio.

nav

The nav tag will create an unordered list of navigation links to the top level items in your site, based on the order you specify in the ‘Manage Content’ section of the administration area. You can also include any nested children in the current section of the site if you’re on a subpage of your site.

Syntax: nav items_array[, nested:true/false, current_class:‘classname’, id:‘nav-id’]

For example, you can include just the top level navigation of your site by using site.navigation.

{% nav site.navigation %}

<ul id="nav">
  <li id="nav-home" class="current">
    <a href="/">Home</a>
  </li>
  <li id="nav-account-management">
    <a href="/account-management/">Account Management</a>
  </li>
  <li id="nav-creating-a-theme">
    <a href="/creating-a-theme/">Creating a Theme</a>
  </li>
  <li id="nav-managing-content">
    <a href="/managing-content/">Managing Content</a>
  </li>
  <li id="nav-harmony-templates">
    <a href="/harmony-templates/">Harmony Templates</a>
  </li>
</ul>

If you’d like to include any nested navigation if the visitor has entered subpages of your site, you can do that by using the nested:true option.

# If you're on /creating-a-theme/stylesheets/
{% nav site.navigation, nested:true %}

<ul id="nav">
  <li id="nav-home">
    <a href="/">Home</a>
  </li>
  <li id="nav-account-management">
    <a href="/account-management/">Account Management</a>
  </li>
  <li class="current" id="nav-creating-a-theme">
    <a href="/creating-a-theme/">Creating a Theme</a>
    <ul id="nav-creating-a-theme-children">
      <li id="nav-creating-a-theme-children-theme-basics">
        <a href="/creating-a-theme/theme-basics/">Theme Basics</a>
      </li>
      <li id="nav-creating-a-theme-children-templates">
        <a href="/creating-a-theme/templates/">Templates</a>
      </li>
      <li id="nav-creating-a-theme-children-includes">
        <a href="/creating-a-theme/includes/">Includes</a>
      </li>
      <li id="nav-creating-a-theme-children-javascripts">
        <a href="/creating-a-theme/javascripts/">JavaScripts</a>
      </li>
      <li class="current" id="nav-creating-a-theme-children-stylesheets">
        <a href="/creating-a-theme/stylesheets/">Stylesheets</a>
      </li>
      <li id="nav-creating-a-theme-children-images">
        <a href="/creating-a-theme/images/">Images</a>
      </li>
    </ul>
  </li>
  <li id="nav-managing-content">
    <a href="/managing-content/">Managing Content</a>
  </li>
  <li id="nav-harmony-templates">
    <a href="/harmony-templates/">Harmony Templates</a>
  </li>
</ul>

You’ll notice that the current location is indicated with a class of current. If you’d like to specify the class used to distinguish the current item, you can pass that in using the current_class option.

{% nav site.navigation, nested:true, current_class:'active' %}

For any further customization, go through your navigation with a for loop and create it exactly the way you like.

<ul id="nav">
  {% for child in site.navigation %}
    <li {% if child.title == item.title %} class="current" {% endif %}>
      <a href="{{ child.url }}">{{ child.title }}</a>
    </li>
  {% endfor %}
</ul>

title

A simple way to add a title tag to the head of your page, using the current item, and its ancestors, including the site title.

Syntax: title [separator]

{% title %} # => <title>Page Title - Parent Page - Site Title</title>
{% title '|' %} # => <title>Page Title | Parent Page | Site Title</title>

ul

The ul tag will make an unordered list of items in an array. It will optionally take an id.

Syntax: ul items[, id:‘ul-id’]

{{ site.navigation | map: 'title' | assign_to: 'titles' }}
{% ul titles, id:'nav-titles' %}

<ul id="nav-titles">
  <li>Home</li>
  <li>Account Management</li>
  <li>Creating a Theme</li>
  <li>Managing Content</li>
  <li>Harmony Templates</li>
</ul>