--- layout: docs title: Templates permalink: /docs/templates/ --- Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language to process templates. All of the standard Liquid [tags](https://shopify.github.io/liquid/tags/) and [filters](https://shopify.github.io/liquid/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

Relative URL

Prepend the baseurl value to the input. Useful if your site is hosted at a subpath rather than the root of the domain.

{% raw %}{{ "/assets/style.css" | relative_url }}{% endraw %}

/my-baseurl/assets/style.css

Absolute URL

Prepend the url and baseurl value to the input.

{% raw %}{{ "/assets/style.css" | absolute_url }}{% endraw %}

http://example.com/my-baseurl/assets/style.css

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. Jekyll v3.2.0 & later.

{% 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 contains '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 %}

Normalize Whitespace

Replace any occurrence of whitespace with a single space.

{% raw %}{{ "a \n b" | normalize_whitespace }}{% 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 %}

To Integer

Convert a string or boolean to integer.

{% raw %}{{ some_var | to_integer }}{% 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']

Inspect

Convert an object into its String representation for debugging.

{% raw %}{{ some_var | inspect }}{% endraw %}

### 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. ```liquid {% raw %}{% include footer.html %}{% endraw %} ``` 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: ```liquid {% raw %}{% include footer.html param="value" variable-param=page.variable %}{% endraw %} ``` These parameters are available via Liquid in the include: ```liquid {% raw %}{{ include.param }}{% endraw %} ``` #### Including files relative to another file You can also choose to include file fragments relative to the current file: ```liquid {% raw %}{% include_relative somedir/footer.html %}{% endraw %} ``` 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: ```liquid {% raw %} {% highlight ruby %} def foo puts 'foo' end {% endhighlight %} {% endraw %} ``` 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: ```liquid {% raw %} {% highlight ruby linenos %} def foo puts 'foo' end {% endhighlight %} {% endraw %} ``` #### 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. ### Link If you want to include a link to a collection's document, a post, a page or a file the `link` tag will generate the correct permalink URL for the path you specify. You must include the file extension when using the `link` tag. ```liquid {% raw %} {% link _collection/name-of-document.md %} {% link _posts/2016-07-26-name-of-post.md %} {% link news/index.html %} {% link /assets/files/doc.pdf %} {% endraw %} ``` You can also use this tag to create a link in Markdown as follows: ```liquid {% raw %} [Link to a document]({% link _collection/name-of-document.md %}) [Link to a post]({% link _posts/2016-07-26-name-of-post.md %}) [Link to a page]({% link news/index.html %}) [Link to a file]({% link /assets/files/doc.pdf %}) {% endraw %} ``` ### 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. ```liquid {% raw %} {% post_url 2010-07-21-name-of-post %} {% endraw %} ``` If you organize your posts in subdirectories, you need to include subdirectory path to the post: ```liquid {% raw %} {% post_url /subdir/2010-07-21-name-of-post %} {% endraw %} ``` 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: ```liquid {% raw %} [Name of Link]({% post_url 2010-07-21-name-of-post %}) {% endraw %} ``` ### Gist Use the `gist` tag to easily embed a GitHub Gist onto your site. This works with public or secret gists: ```liquid {% raw %} {% gist parkr/931c1c8d465a04042403 %} {% endraw %} ``` You may also optionally specify the filename in the gist to display: ```liquid {% raw %} {% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %} {% endraw %} ``` To use the `gist` tag, you'll need to add the [jekyll-gist](https://github.com/jekyll/jekyll-gist) gem to your project.