A comprehensive reference guide for Jekyll covering all Liquid filters, tags, variables, and Markdown syntax.

Collection Variables

directory

Full path to collection’s source directory

{{ site.my_collection.directory }}

Output: /Users/mike/jekyll-project/_my_collection

docs

Array of collection’s documents

{{ site.my_collection.docs.first.url }}

Output: /my_collection/item.html

label

Name of your collection

{{ site.my_collection.label }}

Output: my_collection

output

Whether collection documents output as individual files

{{ site.my_collection.output }}

Output: true

Document Variables

collection

Label of containing collection

{{ site.my_collection.first.collection }}

content

Content of collection item, rendered or un-rendered

{{ site.my_collection.first.content }}

relative_path

Path to document’s source relative to site source

{{ site.my_collection.first.relative_path }}

Global Variables

content - In layout files, rendered content of Post/Page being wrapped page - Page specific info + YAML front matter site - Sitewide info + config settings from _config.yml

Liquid Filters - Array

array_to_sentence_string

{{ page.my_array | array_to_sentence_string }}

Output: a, b, and c

first

Get first element

{{ page.my_array | first }}

last

Get last element

{{ page.my_array | last }}

join

Join array with character

{{ page.my_array | join: ', ' }}

Output: a, b, c

jsonify

Convert Hash/Array to JSON

{{ page.my_array | jsonify }}

Output: ["a","b","c"]

map

Extract attribute from array elements

{{ page.people | map: "name" }}

push

Add object to array

{% assign my_array = my_array | push: 'd' %}

size

Return size of array/string

{{ page.my_array | size }}

Output: 3

sort

Sort array

{{ page.my_array | sort }}
{{ page.posts | sort: 'author' }}
{{ page.posts | sort: 'author', 'last' }}

uniq

Remove duplicates

{{ page.my_array | uniq }}

where

Select objects where key = value

{{ page.people | where: "school", "Stanford" }}

where_exp

Select objects where expression is true

{{ page.people | where_exp: "item", "item.year >= 2016" }}

group_by

Group array items by property

{{ page.people | group_by: "school" }}

Liquid Filters - Date

date

Convert date to another format

{{ site.time | date: "%a, %b %d, %y" }}

Output: Wed, Jan 27, 16

Common format codes:

  • %a - Abbreviated weekday (Sun)
  • %A - Full weekday name (Sunday)
  • %b - Abbreviated month name (Jan)
  • %B - Full month name (January)
  • %d - Day of the month, zero-padded (05)
  • %-d - Day of the month (5)
  • %H - Hour of the day, 24-hour clock (07)
  • %I - Hour of the day, 12-hour clock (04)
  • %m - Month of the year (04)
  • %M - Minute of the hour (09)
  • %p - Meridian indicator uppercase (AM)
  • %S - Second of the minute (05)
  • %Y - Year with century (2016)
  • %y - Year without a century (16)

date_to_long_string

{{ site.time | date_to_long_string }}

Output: 01 January 2016

date_to_rfc822

{{ site.time | date_to_rfc822 }}

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

date_to_string

{{ site.time | date_to_string }}

Output: 01 Jan 2016

date_to_xmlschema

{{ site.time | date_to_xmlschema }}

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

Liquid Filters - Integer

ceil - Round up: {{ 1.2 | ceil }} → 2 floor - Round down: {{ 1.2 | floor }} → 1 round - Round nearest: {{ 1.8 | round }} → 2 plus - Addition: {{ 4 | plus:1 }} → 5 minus - Subtraction: {{ 4 | minus:1 }} → 3 times - Multiplication: {{ 10 | times:3 }} → 30 divided_by - Integer division: {{ 10 | divided_by:3 }} → 3 modulo - Remainder: {{ 3 | modulo:2 }} → 1

Liquid Filters - String

absolute_url

Prepend baseurl and url

{{ '/images/dog.jpeg' | absolute_url }}

relative_url

Prepend baseurl

{{ '/images/dog.jpeg' | relative_url }}

append

Append characters

{{ 'jekyll' | append: '.jpg' }}

Output: jekyll.jpg

prepend

Prepend characters

{{ 'Jekyll' | prepend: 'I love ' }}

Output: I love Jekyll

capitalize

Capitalize first character

{{ "hello world" | capitalize }}

Output: Hello world

downcase

Convert to lowercase

{{ "HELLO" | downcase }}

Output: hello

upcase

Convert to uppercase

{{ "hello" | upcase }}

Output: HELLO

escape

Escape HTML

{{ "<p>Jekyll</p>" | escape }}

strip

Remove whitespace from both ends

{{ '  text  ' | strip }}

Output: text

lstrip

Remove whitespace from beginning

{{ '  text  ' | lstrip }}

rstrip

Remove whitespace from end

{{ '  text  ' | rstrip }}

strip_html

Strip HTML tags

{{ "<p>Jekyll is cool</p>" | strip_html }}

Output: Jekyll is cool

strip_newlines

Strip newline characters

{{ "Hello\nthere" | strip_newlines }}

Output: Hello there

markdownify

Convert Markdown to HTML

{{ "Hello **Jekyll**" | markdownify }}

remove

Remove all occurrences

{{ 'I really really like Jekyll' | remove: 'really' }}

remove_first

Remove first occurrence

{{ 'I really really like Jekyll' | remove_first: 'really' }}

replace

Replace all occurrences

{{ 'I really like Jekyll' | replace: 'really', 'truly' }}

replace_first

Replace first occurrence

{{ 'I really like Jekyll' | replace_first: 'really', 'kinda' }}

slice

Return substring

{{ "hello" | slice: 0 }}

Output: h

{{ "hello" | slice: 1, 3 }}

Output: ell

slugify

Convert to URL slug

{{ "The _config.yml file" | slugify }}

Output: the-config-yml-file

Options: none, raw, default, pretty

split

Divide into array

{{ "a~b" | split:"~" }}

Output: ['a', 'b']

truncate

Truncate to x characters

{{ "I love Jekyll" | truncate: 12 }}

Output: I love Je...

truncatewords

Truncate to x words

{{ "I love Jekyll" | truncatewords: 2 }}

Output: I love...

url_encode

URL encode

{{ "john@example.com" | url_encode }}

Output: john%40example.com

number_of_words

Count words in string

{{ "Hi Jekyll!" | number_of_words }}

Output: 2

Liquid For Loops

Loop Variables

forloop.first - Returns true if first iteration forloop.last - Returns true if last iteration forloop.index - Current iteration (1-indexed) forloop.index0 - Current iteration (0-indexed) forloop.length - Length of entire loop forloop.rindex - Iterations remaining (1-indexed) forloop.rindex0 - Iterations remaining (0-indexed)

Loop Modifiers

limit - Restrict iterations

{% for item in array limit: 2 %}

offset - Start from nth item

{% for item in array offset: 2 %}

reversed - Reverse order

{% for item in array reversed %}

else

Condition when no items in array

{% for item in page.my_array %}
  {{ item }}
{% else %}
  There are no items!
{% endfor %}

Liquid Tags - Control Flow

if / elsif / else

{% if condition %}
  First condition
{% elsif other_condition %}
  Second condition
{% else %}
  Default
{% endif %}

unless

Execute if condition NOT met

{% unless condition %}
  Content
{% endunless %}

case / when

{% case variable %}
{% when 'value1' %}
  First case
{% when 'value2' %}
  Second case
{% else %}
  Default case
{% endcase %}

Operators

== equal != not equal > greater than < less than >= greater or equal <= less or equal or logical or and logical and contains includes substring (string) or element (array)

Liquid Tags - Iteration

for

{% for item in array %}
  {{ item }}
{% endfor %}

break

Stop loop

{% break %}

continue

Skip current iteration

{% continue %}

cycle

Loop through strings

{% cycle 'red', 'blue', 'yellow' %}

increment

Create variable that increases (starts at 0)

{% increment var %}

Output: 0, 1, 2...

decrement

Create variable that decreases (starts at -1)

{% decrement var %}

Output: -1, -2, -3...

Liquid Tags - Other

comment

Don’t output contained text

{% comment %}This won't appear{% endcomment %}

highlight

Code syntax highlighting

{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight %}

include

Insert file from _includes directory

{% include nav.html %}

include_relative

Include file relative to current file

{% include_relative about.html %}

Generate permalink URL

{% link _posts/2017-03-15-my-post.md %}

post_url

Generate permalink for post

{% post_url 2010-07-21-name-of-post %}

raw

No Liquid parsing - wrap content with {​% raw %} and {​% endraw %} tags to prevent Liquid processing.

Liquid Tags - Variable

assign

Create variable

{% assign my_variable = false %}

capture

Capture and assign to variable

{% capture my_variable %}
  Captured text.
{% endcapture %}

Markdown Syntax

Headers

# H1
## H2
### H3
#### H4
##### H5
###### H6

Text Formatting

**bold text**
*italic text*
`inline code`
~~strikethrough~~

[Link text](http://example.com)
![Alt text](/path/to/image.jpg)

Lists

Ordered:

1. First item
2. Second item
3. Third item

Unordered:

* First item
* Second item
* Third item

Blockquotes

> This is a blockquote
> Second line

Code Blocks

```ruby
def hello
  puts "Hello World"
end
```

Horizontal Rule

---

Tables

| Header 1 | Header 2 | Header 3 |
|----------|:--------:|---------:|
| Left     | Center   | Right    |
| aligned  | aligned  | aligned  |

Definition Lists

Term
: Definition

Another Term
: Another definition

Page Variables

page.path - Path to raw post/page page.url - URL without domain page.title - Page title page.content - Page content

Post Variables

page.categories - List of categories page.tags - List of tags page.date - Post date page.excerpt - Post excerpt page.id - Unique identifier page.next - Next post page.previous - Previous post page.title - Post title page.content - Post content

Site Variables

site.time - Current time (when jekyll command runs) site.pages - All pages site.posts - All posts (reverse chronological) site.related_posts - Related posts (for current post) site.static_files - Static files site.html_pages - Pages ending in .html site.collections - All collections site.data - Data from _data directory site.documents - All documents in collections site.categories.CATEGORY - Posts in specific category site.tags.TAG - Posts with specific tag site.url - URL from _config.yml site.baseurl - Baseurl from _config.yml

Custom Config Variables

All variables set in _config.yml are available through site:

{{ site.title }}
{{ site.description }}
{{ site.custom_variable }}

Static File Variables

file.path - Relative path to file file.modified_time - Last modified time file.extname - Extension name

YAML Front Matter

Basic Structure

---
layout: post
title: "Post Title"
date: 2024-01-01
categories: [news, tech]
tags: [html, css]
author: John Doe
---

Data Types

Strings:

title: "My Post"
title: 'My Post'
title: My Post

Numbers:

count: 42
price: 19.99

Booleans:

published: true
featured: false

Dates:

date: 2024-01-01
date: 2024-01-01 14:30:00

Arrays:

categories:
  - news
  - tech

tags: [html, css, javascript]

Hashes/Objects:

author:
  name: John Doe
  email: john@example.com

Common Variables

layout - Layout template to use title - Page/post title date - Publication date categories - Categories for post tags - Tags for post permalink - Custom permalink published - Whether to publish (true/false) excerpt - Custom excerpt

Tips & Best Practices

  1. Use where filter for filtering collections instead of loops when possible
  2. Cache variables - Use assign to store frequently accessed values
  3. Limit array operations - Chaining multiple filters can be slow
  4. Use site.data for structured data instead of hardcoding
  5. Leverage group_by for organizing posts by category/tag/date
  6. Use jsonify for debugging - output variables as JSON
  7. Remember filter order - Filters are applied left to right
  8. Check for nil - Use default filter to handle missing values

Resources