layout: docs
title: Templates
prev_section: migrations
next_section: permalinks

permalink: /docs/templates/

Jekyll uses the Liquid templating language to
process templates. All of the standard Liquid tags and
filters are
supported. Jekyll even adds a few handy filters and tags of its own to make
common tasks easier.

Filters

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.

You can also pass parameters to an include:

{% highlight ruby %}
{% raw %}{% include footer.html param=“value” %}{% endraw %}
{% endhighlight %}

These parameters are available via Liquid in the include:

{% highlight ruby %}
{% raw %}{{ include.param }}{% endraw %}
{% endhighlight %}

Code snippet highlighting

Jekyll has built in support for syntax highlighting of over 100
languages thanks to
Pygments. To use Pygments, you must have Python installed
on your system and set highlighter to pygments in your site’s configuration
file.

Alternatively, you can use Rouge to highlight
your code snippets. It doesn’t support as many languages as Pygments does but
it should fit in most cases and it’s written in pure Ruby ; you don’t need Python
on your system!

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 Pygments’ Lexers
page or the Rouge
wiki.

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. 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
{% 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 %}