Intro to Jekyll

A tool that has a huge impact on how I work

By Johan Ronsse / @wolfr_

What is Jekyll?

“Transform your plain text into static websites and blogs.”

I use Jekyll for

HTML prototypes of applications

I use Jekyll for

My new company website

I use Jekyll for

The Clank website

I use Jekyll for

Small websites for clients

I don't use Jekyll for

CMS-heavy & database driven sites

Getting to know the terminal: awesome screencast

Meet Command Line

Meet the command line

Installing Jekyll

Installing Jekyll is "straightforward"


~ $ gem install jekyll

Windows users

Installing Jekyll on Windows

Heads up: Rubygems

For the gem command to work you need to the RubyGems site and follow the instructions.


~ $ gem update --system
~ $ # you might have to use sudo

Heads up (2): RVM

For Ruby to work nicely on your system it might make sense to install rvm so you can have a more recent version of ruby than 1.8.7 that ships with Mac OS

Heads up (3): Xcode

You might want to install the Xcode developer tools (you can get Xcode from the Mac app store)

Heads up (4): Brew

People tell me it's better to use brew than force install everything with sudo

Generating a new Jekyll site


~ $ cd ~/Sites/
~ $ jekyll new my-awesome-site
~ $ cd my-awesome-site

Watch the site

The serve command auto updates the generated site when you make changes.


~ $ jekyll serve -w 
# => Now browse to http://localhost:4000

What you'll see

Let's examine the files

About the file structure

_site/: this is the folder for your generated site
_layouts/: this is the folder containing your layouts
_includes/: this is the folder for partials (think HTML includes)
_config.yml: this is the config file
index.html: base page
css/: CSS folder

Layouts and includes

The first concept you need to understand is layouts (demo)

A Layout

A layout is basically a template in which you can inject content.


---
layout: my-sample-layout
---

This is the content.

my-sample-layout.html



{% include head.html %}
{% include header.html %}

{{ content }}

{% include footer.html %}

Includes

An include refers to a file in the _includes folder:



{% include head.html %}

head.html might for instance contain the <head> section of a site.

YAML front matter and Liquid

Every content page can be prepended with YAML front matter. Within the YAML front matter you can add some metadata to a page.


---
layout: my-sample-layout
my-custom-statement: my-value
---

This is the content.

YAML front matter and Liquid

These values can be used in the content:


---
layout: my-sample-layout
my-custom-statement: my-value
---

This is the content.

{{ page.my-custom-statement }}

YAML front matter and Liquid

Or, more interestingly, in an "if" clause:


---
layout: my-sample-layout
my-custom-statement: my-value
---

This is the content.

{% if page.my-custom-statement == "my-value" %}
Render this part of the HTML
{% endif %}

Why is this useful?

For example, show all the states of a form: erorr, success, normal


---
layout: my-sample-layout
error: true
---

This is the content.

{% if page.error }
Render this part of the HTML
{% endif %}

{% if page.success }
Render this part of the HTML
{% endif %}

Front matter in practice

Task: show all the states of a form: erorr, success, normal

Make form.html, form-error.html, form-success.html files
Make them use the same layout
Make an include: my-form.html
Require the include in all html files
Within the include, build up your IF/ELSE logic

(demo)

For and cycle tag

The for tag creates a for loop. The cycle tag allows you to cycle through a known data set.


---
layout: my-sample-layout
---

{% for num in (1...3) %}
{% cycle 'a', 'b', 'c' %}
{% endfor %}

Cycle tag

Why is this useful? Anything with a lot of iteration. For example, using real data in prototype:

Blogging with Jekyll

Jekyll contains a pre-built blogging mechanism.

Blogging with Jekyll

The _posts folder contains markdown files:

2013-08-29-welcome-to-jekyll.markdown

Blogging with Jekyll

The posts are:

Written in markdown
You can use Textile
You can set your markdown parser if you want (Maruku, kramdown,...)

Adding an RSS feed

To add an atom feed to your site just add an atom.xml file with the correct values.

Sample sites

There are sample sites on Github. A lot of people made their Jekyll sites open source so other people can learn.

Cactus

Cactus is a responsive Jekyll theme that contains a blog.

Footnotes with Kramdown

This is for creating nice footnotes like on daringfireball.net and marco.org:

Footnotes with Kramdown

First, specify your markdown engine in your config file:


markdown: kramdown

Intermezzo: the Jekyll site config object

The _config.yml contains a global "settings" object that specifies things about your site

Where it should be generated
How permalinks should look
Which markdown parser to use
After how many pages the blog should paginate
Etc.

Footnotes with Kramdown

Next, juse use markdown like this in a blog post:


This is a text with a
footnote[^1].

[^1]: And here is the definition.

Documentation on kramdown website.

Markdown/kramdown

You could even make tables if you want to:

Pagination

Regular blog code: you would use site.posts


          
{% for post in site.posts %}

  
    {{ post.title }}
    Posted on {{ post.date | date: "%B %d, %Y" }} by [author name]
  
  
    {{ post.content }}
  

{% endfor %}

Pagination

If you need pagination blog code: you would use paginator.posts


          
  {% for post in paginator.posts %}
  
    
      {{ post.title }}
      Posted on {{ post.date | date: "%B %d, %Y" }} by [author name]
    
    
      {{ post.content }}
    
  
  {% endfor %}

Pagination

Also, add some pagination code liike this:



  {% if paginator.previous_page %}
    {% if paginator.previous_page == 1 %}
        Previous
      {% else %}
        Previous
      {% endif %}
  {% else %}
    Previous
  {% endif %}

  Page: {{ paginator.page }} of {{ paginator.total_pages }}

  {% if paginator.next_page %}
    Next
  {% else %}
    Next
  {% endif %}

Pagination config

Set this in the _config.yml and adjust if necessary:


      
paginate: 7
paginate_path: "blog/page:num"

How to have nice permalinks (without .html)

Make a folder structure yourself:


          portfolio.html
          becomes portfolio/index.html

How to have nice permalinks (without .html)

Alternative: use permalinks in YAML front matter, see Jekyll site

Providing test websites for clients that can live in a subdirectory

Problem: I want to provide static test sites to clients
Solution: set a {{ baseurl }} in _config.yml


          baseurl: my-test-site

For each file reference instead of:


          <link rel="stylesheet" href="css/screen.css" type="text/css" media="screen">

Use {{ baseurl }} instead:


        <link rel="stylesheet" href="{% unless site.baseurl == "/" %}{{ site.baseurl }}{% endunless %}/css/screen.css" type="text/css" media="screen">

Looking for a cleaner solution!

Jekyll plugins

My experience so far

A Jekyll plugin

Is a Ruby (.rb) file in the _plugins folder)

Example plugin: Cycle random


module Jekyll

  class Random < Liquid::Tag
    def initialize(tag_name, arr, tokens)
       super
       @arr = arr.split(",")
    end

    def render(context)
      @arr[rand(@arr.size)] 
    end
  end

end

Liquid::Template.register_tag('cyclerand', Jekyll::Random)

Sitemaps with Jekyll

Just a sitemap.xml file that lists posts and pages (see this link)


<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

  {% for post in site.posts %}
  <url>
    <loc>{{ site.baseurl }}{{ post.url }}</loc>
    {% if post.lastmod == null %}
    <lastmod>{{ post.date | date_to_xmlschema }}</lastmod>
    {% else %}
    [...]

Adding open graph metadata to your site



{% capture header %}



{% if page.title %}
  
  
{% else %}
  
{% endif %}

{% if site.title %}
  
{% endif %}

{% if page.url %}
  
{% endif %}

{% if page.date %}
  
{% endif %}

{% if site.owner_link %}
  
{% endif %}

{% endcapture %}{{ header | strip_newlines }}

Why you should add open graph metadata to your site

Get avatars and extra meta data in search results and social media posts

SEO benefit? Dunno, but it doesn't take long to add.

Thanks!

By Johan Ronsse / @wolfr_