Jekyll Reference
Kip Landergren
(Updated: )
My cheat sheet for Jekyll covering helpful documentation links, terminology, and authoring tips.
Contents
Gotchas
Hash access does not support ruby symbols as keys and does not warn. More info in this GitHub issue.
Filters
absolute_url
Takes a url and returns the absolute path of the URI:
<link rel="canonical" href="{{ page.url | absolute_url }}">
Tags
highlight
Note: uses the “short name” as first argument.
Generate list of support languages and lexers:
bundle exec rougify list
- list of supported languages and lexers
- list of supported tokens (note: not all are listed there, see lib/rouge/token.rb for complete list)
include
Official documentation on include
usage.
Pull in the contents of $PROJECT_ROOT/_includes/header.html
:
{% include header.html %}
Pass variables to an include
, referrable inside the include
via {{ include.my_variable }}
:
{% include my-file.html my_variable="foo" %}
Passing HTML or content containing other variables to an include
using capture
:
{% capture my_variable %}
Can use {{ page.some_variable }} and <em>can contain</em> HTML
{% endcapture %}
{% include my-file.html my_variable=my_variable bar="bar" %}
More info on this Stack Overflow answer to Passing parameters to inclusion in Liquid templates.
Combine with highlight:
{% highlight xml %}{% include svg/blue-rectangle.svg %}{%- endhighlight -%}
raw
Curly brackets or literal liquid tags can be rendered by wrapping in {% raw %}
and {% endraw %}
. Example:
{% raw %}
insert any text with ‘{%’ or ‘}}’
{% endraw %}
Supporting Markdown Files
From the docs:
“Jekyll converts Markdown to HTML using the Markdown filter specified in your config file. Files must have a Markdown file extension and front matter in order for Jekyll to convert them.”
Jekyll Terminology
- collection
- A group of related content. Becomes accessible through
site
- front matter
- YAML region marked by triple dashes (
---
). Must be first characters in file.