Jekyll Cheat Sheet

From WikiOD

Here is the cheatsheat of Jekyll and basic guide on how to use Jekyll {% raw %}

Installation[edit | edit source]

# Install the gems
gem install jekyll bundler
# Create a new site at `./myblog`
jekyll new myblog
cd myblog
# Optional: if you're targeting github-pages,
# use this Gemfile instead.
cat > Gemfile <<-END
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
END
bundle exec jekyll serve

See: Jekyll quickstart
See: github/pages-gem

Directories[edit | edit source]

./
├── _config.yml
│
├── _data/
│   └── ...
│
├── _drafts/
│   └── ...
│
├── _posts/
│   └── 2014-01-01-hello.md
│
├── _layouts/
│   ├── default.html
│   └── post.html
│
├── _includes/             - partials
│   ├── header.html
│   └── footer.html
│
└── _site/
    └── ...

{: .-box-chars}

Front-matter[edit | edit source]

{: .-three-column}

Basic frontmatter[edit | edit source]

---
layout: post
title: Hello
---
Hello! this is my post.

{: data-line=“1,2,3,4”}

Attach metadata to a page by adding them on top of the page, delimited by ---. See: Front-matter

Other frontmatter stuff[edit | edit source]

permalink: '/hello'
published: false
category: apple
categories: ['html', 'css']
tags: ['html', 'css']

Configuration[edit | edit source]

In _config.yml: {: .-setup}

source: .
destination: _site
exclude:
- Gemfile
- Gemfile.lock
include: ['.htaccess']

All config keys are optional. See: Configuration

Markup[edit | edit source]

{: .-three-column}

Page variables[edit | edit source]

<title>
  {{ page.title }}
</title>

{: data-line=“2”}

Filters[edit | edit source]

<p>
  {{ page.description | truncate_words: 20 }}
</p>

{: data-line=“2”}

Loops[edit | edit source]

{% for post in site.posts %}
  <a href="{{ post.url }}">
    <h2>{{ post.title }}</h2>
    <p>{{ post.date | date_to_string }}</p>
  </a>
{% endfor %}

{: data-line=“1,6”}

Dates[edit | edit source]

{{ page.date | date: "%b %d, %Y" }}

Conditionals[edit | edit source]

{% if page.image.feature %}
  ...
{% elsif xyz %}
  ...
{% else %}
  ...
{% endif %}

{: data-line="1,3,5,7 }

{% if page.category == 'React' %}
{% if page.category == 'React' or page.featured %}
{% if page.tags contains 'Featured' %}

Case[edit | edit source]

{% case shipping.title %}
  {% when 'international' %}
     Arriving in 2-3 weeks
  {% when 'Domestic' %}
     Arriving in 2-3 days
  {% else %}
     Thank you for your order!
{% endcase %}

{: data-line=“1,2,4,6,8”}

Includes (partials)[edit | edit source]

{% include header.html %}

{: data-line=“1”}

<!-- Including local vars -->
{% include header.html page=page %}

{: data-line=“2”}

Comments[edit | edit source]

{% comment %}
  This is a comment!
{% endcomment %}

{: data-line=“1,3”}

Variables[edit | edit source]

Top-level variables[edit | edit source]

Template:Site | Data from config.yml |
Template:Page | From frontmatter, and page-specific info |
Template:Content | HTML content (use in layouts) |
Template:Paginator | Paginator |

See: Variables

Site[edit | edit source]

{{ site.time }}

{: .-setup}

site.time | Current time |
site.pages | List of pages |
site.posts | List of blog posts |
site.related_posts | List of posts related to current |
site.categories.CATEGORY | List |
site.tags.TAG | List |
site.static_files | List |

Page[edit | edit source]

{{ page.content }}  - un-rendered content
{{ page.title }}
{{ page.excerpt }}  - un-rendered excerpt
{{ page.url }}
{{ page.date }}
{{ page.id }}       - unique id for RSS feeds
{{ page.categories }}
{{ page.tags }}
{{ page.path }}
{{ page.dir }}
{{ page.excerpt | remove: '<p>' | remove: '</p>' }}
{{ page.excerpt | strip_html }}
<!-- blog pagination: -->
{{ page.next }}
{{ page.previous }}

Filters[edit | edit source]

{: .-three-column}

Dates[edit | edit source]

{{ site.time | date: "%Y %m %d" }}

{: .-setup}

date_to_xmlschema | → 2008-11-07T13:07:54-08:00 |
date_to_rfc822 | → Mon, 07 Nov 2008 13:07:54 -0800 |
date_to_string | → 07 Nov 2008 |
date_to_long_string | → 07 November 2008 |
date: ‘%Y %m %d’ | → 2017 Nov 7 |

Preprocessors[edit | edit source]

{{ page.description | markdownify }}

{: .-setup}

Filter Description
textilize Textile
markdownify Markdown
jsonify JSON
sassify Sass
scssify SCSS
smartify Smartypants

Array filters[edit | edit source]

{{ site.pages | where: "year", "2014" }}

{: .-setup}

Filter Description
where: “year”, “2014”
where_exp: “item”, “item.year >= 2014”
group_by: “genre” {name, items}
group_by_exp: “item”, “item.genre” {name, items}
sort
sort: ‘author’
uniq
first
last
join: ‘,’
array_to_sentence_string "X, Y and Z"
map: ‘post’ Works like ‘pluck’
size
push: ‘xxx’ Adds an item

String filters[edit | edit source]

{{ page.title | default: "xxx" }}

{: .-setup}

Filter Description
default: ‘xxx’
upcase
downcase
remove: ‘p’
replace: ‘super’, ‘mega’
remove_first: ‘p’
replace_first: ‘super’, ‘mega’
truncate: 5
truncatewords: 20
prepend: ‘Mr. ’
append: ‘Jr.’
camelize
capitalize
strip_html
strip_newlines
newlines_to_br
split: ‘,’
escape
escape_once
slice: -3, 3

See: String filters

String filters (Jekyll-only)[edit | edit source]

{{ page.excerpt | number_of_words }}

{: .-setup}

Filter Description
number_of_words
slugify
xml_escape CDATA
cgi_escape foo%2Cbar
uri_escape foo,%20bar

Numbers[edit | edit source]

{{ site.posts.size | minus: 2 }}

{: .-setup}

Filter Description
minus: 2
plus: 2
times: 2
divided_by: 2
modulo: 2
ceil
floor
round

Paginator[edit | edit source]

Paginator setup[edit | edit source]

Add this to _config.yml: {: .-setup}

paginate: 5
paginate_path: "blog/:num"

See: Paginator

Numbers[edit | edit source]

{{ paginator.page }}         - page number
{{ paginator.total_posts }}
{{ paginator.total_pages }}
{{ paginator.per_page }}

Iterating through posts[edit | edit source]

{% for post in paginator.posts %} ... {% endfor %}

Previous button[edit | edit source]

{% if paginator.total_pages > 1 %}
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path }}">Previous</a>
  {% else %}
  {% endif %}
{% endif %}
{{ paginator.next_page }}     - page number
{{ paginator.next_page_path }}

Blogging[edit | edit source]

Paths[edit | edit source]

_posts/YEAR-MONTH-DAY-title.md

See: Blogging

Image paths[edit | edit source]

![My helpful screenshot]({{ site.url }}/assets/screenshot.jpg)

See: Image paths

Drafts[edit | edit source]

vi _drafts/a-draft-post.md
jekyll build --drafts

Posts in _drafts only show up in development, but not production. See: Drafts

Defining excerpts[edit | edit source]

---
title: My blog post
excerpt: This post is about cats
---

Hello, let's talk about cats. (···)

Put a key excerpt in the frontmatter. See: Excerpts

Displaying excerpts[edit | edit source]

{{ post.excerpt }}
{{ post.excerpt | remove: '<p>' | remove: '</p>' }}
{{ post.excerpt | strip_html }}

Excerpt separator[edit | edit source]

---
excerpt_separator: <!--more-->
---

Excerpt here
<!--more-->
More post body here

Alternatively, you can put excerpts inline in your post by defining excerpt_separator.

Permalinks[edit | edit source]

# _config.yml
permalink: date   # /:categories/:year/:month/:day/:title.html
permalink: pretty # /:categories/:year/:month/:day/:title/
permalink: none   # /:categories/:title.html
permalink: "/:title"

See: Permalinks

More features[edit | edit source]

Data[edit | edit source]

_data/members.yml

{: .-setup}

{% for member in site.data.members %}
  ...
{% endfor %}

See: Data

Collections[edit | edit source]

# _config.yml
collections:
  - authors

{: .-setup}

# _/authors/a-n-roquelaire.md
---
name: A. N. Roquelaire
real_name: Anne Rice
---
{% for author in site.authors %}

See: Collections

Code highlighter[edit | edit source]

{% highlight ruby linenos %}
def show
  ...
end
{% endhighlight %}

Integration[edit | edit source]

Bundler[edit | edit source]

In _plugins/bundler.rb: {: .-setup}

require "bunder/setup"
Bundler.require :default

Compass[edit | edit source]

Also see[edit | edit source]

{: .-one-column}

{% endraw %}

Credit:rstacruz