cheatsheets/jekyll.md at 8c011309504ab959618370b57e1d51b174609b74

11 KiB

Raw Blame History

title

jekyll_escape

layout

Installation

# Install the gems
gem install jekyll bundler

# Create a new site at `./myblog`
jekyll new myblog

cd myblog
bundle exec jekyll serve

See: Jekyll quickstart

Installation (GitHub pages version)

# Requires bundler
gem install bundler

# Build the Gemfile
cat > Gemfile <<-END
  source 'https://rubygems.org'
  gem 'github-pages', group: :jekyll_plugins
END

# Install gems
bundle

# Start server
bundle exec jekyll serve

This is the recommended setup, especially if you're using GitHub pages. See: github/pages-gem

Directories

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

Front-matter

{: .-three-column}

Basic frontmatter

---
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

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

Configuration

In _config.yml: {: .-setup}

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

See: Configuration

Markup

Page variables

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

<!-- Filters -->
<p>{{ page.description | truncate_words: 20 }}

Loops

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

Dates

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

Conditionals

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

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

Case

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

Includes (partials)

{% include header.html %}

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

Comments

{% comment %}
{% endcomment %}

Expression

Top-level variables

{{ site }}       - from config.yml
{{ page }}       - from frontmatter, and page-specific info
{{ content }}    - html content (use in layouts)
{{ paginator }}  - ...

See: Variables

Site

{{ site.time }}                 - current time
{{ site.pages }}                - list of pages
{{ site.posts }}                - list of posts
{{ site.related_posts }}        - list
{{ site.categories.CATEGORY }}  - list
{{ site.tags.TAG }}             - list

{{ site.static_files }}

Page

{{ 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 }}
{{ post.excerpt | remove: '<p>' | remove: '</p>' }}
{{ post.excerpt | strip_html }}

<!-- blog pagination: -->
{{ page.next }}
{{ page.previous }}

Paginator

Paginator setup

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

paginate: 5
paginate_path: "blog/:num"

See: Paginator

Numbers

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

Iterating through posts

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

Previous button

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

Paths

_posts/YEAR-MONTH-DAY-title.md

See: Blogging

Image paths

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

See: Image paths

Drafts

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

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

Defining excerpts

---
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

{{ post.excerpt }}

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

Excerpt separator

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

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

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

Permalinks

# _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

Data

_data/members.yml

{: .-setup}

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

See: Data

Collections

# _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

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

Helpers and filters

{: .-three-column}

Dates

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

{: .-setup}

Preprocessors

{{ page.description | markdownify }}

{: .-setup}

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

Array filters

{{ 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_setentence_string`	→ `"X, Y and Z"`
---	---
`map:` 'post'	Works like 'pluck'
---	---
`size`
`push:` 'xxx'	Adds an item

String filters

{{ 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)

{{ page.excerpt | number_of_words }}

{: .-setup}

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

Numbers

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

{: .-setup}

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

Integration

Bundler

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

require "bunder/setup"
Bundler.require :default

Compass

Also see

{: .-one-column}

Jekyll docs jekyllrb.com
CloudCannon Jekyll cheatsheet cloudcannon.com
Jekyll: templates jekyllrb.com
Liquid: output shopify.com
Liquid: logic shopify.com
Liquid: filters shopify.com
Liquid for designers github.com/Shopify {: .-also-see}

{% endraw %}

11 KiB Raw Blame History

Installation

Installation (GitHub pages version)

Directories

Front-matter

Basic frontmatter

Other frontmatter stuff

Configuration

Markup

Page variables

Loops

Dates

Conditionals

Case

Includes (partials)

Comments

Expression

Top-level variables

Site

Page

Paginator

Paginator setup

Numbers

Iterating through posts

Previous button

Blogging

Paths

Image paths

Drafts

Defining excerpts

Displaying excerpts

Excerpt separator

Permalinks

More features

Data

Collections

Code highlighter

Helpers and filters

Dates

Preprocessors

Array filters

String filters

String filters (Jekyll-only)

Numbers

Integration

Bundler

Compass

Also see

11 KiB

Raw Blame History