--- layout: docs title: Templates permalink: /docs/templates/ --- Jekyll uses the [Liquid](https://github.com/Shopify/liquid/wiki) templating language to process templates. All of the standard Liquid [tags](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#tags) and [filters](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#standard-filters) are supported. Jekyll even adds a few handy filters and tags of its own to make common tasks easier. ## Filters
Description Filter and Output

Date to XML Schema

Convert a Date into XML Schema (ISO 8601) format.

{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}

2008-11-07T13:07:54-08:00

Date to RFC-822 Format

Convert a Date into the RFC-822 format used for RSS feeds.

{% raw %}{{ site.time | date_to_rfc822 }}{% endraw %}

Mon, 07 Nov 2008 13:07:54 -0800

Date to String

Convert a date to short format.

{% raw %}{{ site.time | date_to_string }}{% endraw %}

07 Nov 2008

Date to Long String

Format a date to long format.

{% raw %}{{ site.time | date_to_long_string }}{% endraw %}

07 November 2008

Where

Select all the objects in an array where the key has the given value.

{% raw %}{{ site.members | where:"graduation_year","2014" }}{% endraw %}

Where Expression

Select all the objects in an array where the expression is true.

{% raw %}{{ site.members | where_exp:"item", "item.graduation_year == 2014" }}{% endraw %} {% raw %}{{ site.members | where_exp:"item", "item.graduation_year < 2014" }}{% endraw %} {% raw %}{{ site.members | where_exp:"item", "item.projects includes 'foo'" }}{% endraw %}

Group By

Group an array's items by a given property.

{% raw %}{{ site.members | group_by:"graduation_year" }}{% endraw %}

[{"name"=>"2013", "items"=>[...]}, {"name"=>"2014", "items"=>[...]}]

XML Escape

Escape some text for use in XML.

{% raw %}{{ page.content | xml_escape }}{% endraw %}

CGI Escape

CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.

{% raw %}{{ "foo,bar;baz?" | cgi_escape }}{% endraw %}

foo%2Cbar%3Bbaz%3F

URI Escape

URI escape a string.

{% raw %}{{ "foo, bar \baz?" | uri_escape }}{% endraw %}

foo,%20bar%20%5Cbaz?

Number of Words

Count the number of words in some text.

{% raw %}{{ page.content | number_of_words }}{% endraw %}

1337

Array to Sentence

Convert an array into a sentence. Useful for listing tags.

{% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}

foo, bar, and baz

Markdownify

Convert a Markdown-formatted string into HTML.

{% raw %}{{ page.excerpt | markdownify }}{% endraw %}

Smartify

Convert "quotes" into “smart quotes.”

{% raw %}{{ page.title | smartify }}{% endraw %}

Converting Sass/SCSS

Convert a Sass- or SCSS-formatted string into CSS.

{% raw %}{{ some_scss | scssify }}{% endraw %} {% raw %}{{ some_sass | sassify }}{% endraw %}

Slugify

Convert a string into a lowercase URL "slug". See below for options.

{% raw %}{{ "The _config.yml file" | slugify }}{% endraw %}

the-config-yml-file

{% raw %}{{ "The _config.yml file" | slugify: 'pretty' }}{% endraw %}

the-_config.yml-file

Data To JSON

Convert Hash or Array to JSON.

{% raw %}{{ site.data.projects | jsonify }}{% endraw %}

Sort

Sort an array. Optional arguments for hashes: 1. property name 2. nils order (first or last).

{% raw %}{{ page.tags | sort }}{% endraw %}

{% raw %}{{ site.posts | sort: 'author' }}{% endraw %}

{% raw %}{{ site.pages | sort: 'title', 'last' }}{% endraw %}

Sample

Pick a random value from an array. Optional: pick multiple values.

{% raw %}{{ site.pages | sample }}{% endraw %}

{% raw %}{{ site.pages | sample:2 }}{% endraw %}

Array Filters

Push, pop, shift, and unshift elements from an Array.

These are NON-DESTRUCTIVE, i.e. they do not mutate the array, but rather make a copy and mutate that.

{% raw %}{{ page.tags | push: 'Spokane' }}{% endraw %}

['Seattle', 'Tacoma', 'Spokane']

{% raw %}{{ page.tags | pop }}{% endraw %}

['Seattle']

{% raw %}{{ page.tags | shift }}{% endraw %}

['Tacoma']

{% raw %}{{ page.tags | unshift: "Olympia" }}{% endraw %}

['Olympia', 'Seattle', 'Tacoma']

### Options for the `slugify` filter The `slugify` filter accepts an option, each specifying what to filter. The default is `default`. They are as follows (with what they filter): - `none`: no characters - `raw`: spaces - `default`: spaces and non-alphanumeric characters - `pretty`: spaces and non-alphanumeric characters except for `._~!$&'()+,;=@` ## Tags ### Includes If you have small page fragments that you wish to include in multiple places on your site, you can use the `include` tag. {% highlight ruby %} {% raw %}{% include footer.html %}{% endraw %} {% endhighlight %} Jekyll expects all include files to be placed in an `_includes` directory at the root of your source directory. This will embed the contents of `/_includes/footer.html` into the calling file.
ProTip™: Use variables as file name

The name of the file you wish to embed can be literal (as in the example above), or you can use a variable, using liquid-like variable syntax as in {% raw %}{% include {{my_variable}} %}{% endraw %}.

You can also pass parameters to an include. Omit the quotation marks to send a variable's value. Liquid curly brackets should not be used here: {% highlight ruby %} {% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %} {% endhighlight %} These parameters are available via Liquid in the include: {% highlight ruby %} {% raw %}{{ include.param }}{% endraw %} {% endhighlight %} #### Including files relative to another file You can also choose to include file fragments relative to the current file: {% highlight ruby %} {% raw %}{% include_relative somedir/footer.html %}{% endraw %} {% endhighlight %} You won't need to place your included content within the `_includes` directory. Instead, the inclusion is specifically relative to the file where the tag is being used. For example, if `_posts/2014-09-03-my-file.markdown` uses the `include_relative` tag, the included file must be within the `_posts` directory, or one of its subdirectories. You cannot include files in other locations. All the other capabilities of the `include` tag are available to the `include_relative` tag, such as using variables. ### Code snippet highlighting Jekyll has built in support for syntax highlighting of over 60 languages thanks to [Rouge](http://rouge.jneen.net). Rouge is the default highlighter in Jekyll 3 and above. To use it in Jekyll 2, set `highlighter` to `rouge` and ensure the `rouge` gem is installed properly. Alternatively, you can use [Pygments](http://pygments.org) to highlight your code snippets. To use Pygments, you must have Python installed on your system, have the `pygments.rb` gem installed and set `highlighter` to `pygments` in your site's configuration file. Pygments supports [over 100 languages](http://pygments.org/languages/) To render a code block with syntax highlighting, surround your code as follows: {% highlight text %} {% raw %} {% highlight ruby %} def foo puts 'foo' end {% endhighlight %} {% endraw %} {% endhighlight %} The argument to the `highlight` tag (`ruby` in the example above) is the language identifier. To find the appropriate identifier to use for the language you want to highlight, look for the “short name” on the [Rouge wiki](https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexers) or the [Pygments' Lexers page](http://pygments.org/docs/lexers/). #### Line numbers There is a second argument to `highlight` called `linenos` that is optional. Including the `linenos` argument will force the highlighted code to include line numbers. For instance, the following code block would include line numbers next to each line: {% highlight text %} {% raw %} {% highlight ruby linenos %} def foo puts 'foo' end {% endhighlight %} {% endraw %} {% endhighlight %} #### Stylesheets for syntax highlighting In order for the highlighting to show up, you’ll need to include a highlighting stylesheet. For an example stylesheet you can look at [syntax.css](https://github.com/mojombo/tpw/tree/master/css/syntax.css). These are the same styles as used by GitHub and you are free to use them for your own site. If you use `linenos`, you might want to include an additional CSS class definition for the `.lineno` class in `syntax.css` to distinguish the line numbers from the highlighted code. ### Post URL If you would like to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify. {% highlight text %} {% raw %} {% post_url 2010-07-21-name-of-post %} {% endraw %} {% endhighlight %} If you organize your posts in subdirectories, you need to include subdirectory path to the post: {% highlight text %} {% raw %} {% post_url /subdir/2010-07-21-name-of-post %} {% endraw %} {% endhighlight %} There is no need to include the file extension when using the `post_url` tag. You can also use this tag to create a link to a post in Markdown as follows: {% highlight text %} {% raw %} [Name of Link]({% post_url 2010-07-21-name-of-post %}) {% endraw %} {% endhighlight %} ### Gist Use the `gist` tag to easily embed a GitHub Gist onto your site. This works with public or secret gists: {% highlight text %} {% raw %} {% gist parkr/931c1c8d465a04042403 %} {% endraw %} {% endhighlight %} You may also optionally specify the filename in the gist to display: {% highlight text %} {% raw %} {% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %} {% endraw %} {% endhighlight %} To use the `gist` tag, you'll need to add the [jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project.