layout | title | prev_section | next_section | permalink |
---|---|---|---|---|
docs |
Templates |
migrations |
permalinks |
/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.
Description | Filter and Output |
---|---|
Date to XML Schema Convert a Date into XML Schema (ISO 8601) format. |
|
Date to RFC-822 Format Convert a Date into the RFC-822 format used for RSS feeds. |
|
Date to String Convert a date to short format. |
|
Date to Long String Format a date to long format. |
|
Where Select all the objects in an array where the key has the given value. |
|
Group By Group an array's items by a given property. |
|
XML Escape Escape some text for use in XML. |
|
CGI Escape CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements. |
|
URI Escape URI escape a string. |
|
Number of Words Count the number of words in some text. |
|
Array to Sentence Convert an array into a sentence. Useful for listing tags. |
|
Textilize Convert a Textile-formatted string into HTML, formatted via RedCloth |
|
Markdownify Convert a Markdown-formatted string into HTML. |
|
Converting Sass/SCSS Convert a Sass- or SCSS-formatted string into CSS. |
|
Slugify Convert a string into a lowercase URL "slug" by replacing every sequence of spaces and non-alphanumeric characters with a hyphen. |
|
Data To JSON Convert Hash or Array to JSON. |
|
Sort Sort an array. Optional arguments for hashes: 1. property name 2. nils order (first or last). |
|
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
<source>/_includes/footer.html
into the calling file.
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
<code>{% raw %}{% include {{my_variable}} %}{% endraw %}</code>.
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 %}
You can also choose to include files 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.
All the other capaibilities of the include
tag are available to the include_relative
tag.
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.
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 %}
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.
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 %}
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 %}