#WordPress to #Jekyll Part 2 - How Jekyll Works
Published on 14 Mar 2016Tags #Jekyll #GitHub Pages
After I have presented arguments for a static site in the first post in this series, I will provide you with an introduction to Jekyll, the static site generator which I am using for this site. Checkout StaticGen for more static site generators and the popularity of Jekyll.
Directory structure
Jekyll implements a distinct directory structure to store metadata as well as files with a special purpose like posts, drafts and layouts. The following table explains those special directories and files.
| Item | Usage |
|---|---|
| _config.yml | File containing the configuration for your blog |
| _layouts | Directory with templates for posts, pages and other content types |
| _includes | Directory structure containing files that can be included in layouts as well as content |
| _posts | Directory containing blog posts |
| _drafts | Directory containing drafts for your blog posts |
| _data | Directory containing data to be processed during site generation |
| _site | Directory containing the resulting static site |
Everything else is copied to _site directory without any modifications.
Install Jekyll on Windows
Jekyll is based on Ruby. The easiest way to install Ruby on Windows is using Chocolatey. If you haven’t heard of Chocolatey, you should definately take a look at it because makes installing applications a lot easier.
- Open a command prompt
- Install Ruby using Chcolatey:
choco install ruby - Re-open a command prompt
- Install Jekyll using Ruby:
gem install jekyll - Install Jekyll plugins supported by GitHub Pages:
gem install github-pages
Note that you are not limited to using plugins that are supported by GitHub Pages. I was planning to use GitHub Pages for hosting my site, so I restricted myself to those plugins.
Using Jekyll
The following commands are used to work with Jekyll:
- Create a new blog:
jekyll new mysite - Building your site:
jekyll build - Previewing your site with the builtin web server on http://localhost:4000:
jekyll serve - Cleaning the site directory:
jekyll clean
Anatomy of a Post
A post can be stored anywhere in the _posts directory. I decided to use yearly subdirectories because the list was getting too long ;-)
A post consist of a so-called frontmatter and the content. The following excerpt shows the frontmatter for the first post in this series:
---
title: 'WordPress to Jekyll Part 1 - Arguments for a Static Site'
date: 2016-03-10T12:02:56+01:00
author: Nicholas Dille
layout: post
permalink: /blog/2016/03/10/wordpress-to-jekyll-part-1-arguments-for-a-static-site/
tags:
- WordPress
- Jekyll
- GitHub Pages
- Azure
- Azure Websites
---
Place your content here
Many of the fields in the frontmatter above are selfexplanatory, therefore, I’d like to take a closer look at only a few of them:
-
titlecontains the title of the post as displayed on the generated web page -
permalinkdefines the URL where the post will be accessible. This field is especially important for blog migrations to preserve incoming links -
layoutspecifies the template for the layout of this page (in this example:post)
Using the value of the layout field, it is possible to trace how the static page is generated. The layout template usually contains some code to process some fields from the frontmatter as well as the content. To reference fields defined in the frontmatter of the post, the field is enclosed in double curly brackets. Fields are presented under the page object.
---
layout: default
---
<div class="post">
<h1 class="post-title">{{ page.title }}</h1>
<span class="post-date">Published on {{ page.date | date_to_string }}</span>
{{ content }}
</div>
Note that the post layout also contains a frontmatter which references the default layout template. This template finally contains the structure of an HTML page:
<!DOCTYPE html>
<html lang="en-us">
{% include head.html %}
<body class="theme-base-0d layout-reverse">
{% include sidebar.html %}
<div class="content container">
{{ content }}
</div>
</body>
</html>
The default layout template uses include statements ({% include ... %}) for the Liquid template engine to include files located on the _includes subdirectory. The following section demonstrates how the Liquid template engine is used for creating complex pages.
index.html
The index.html located in the root of a Jekyll blog is used for
---
layout: default
title: Home
---
<div class="posts">
{% for post in paginator.posts %}
<div class="post">
<h1 class="post-title"><a href="{{ post.url }}">{{ post.title }}</a></h1>
<span class="post-date">Published on {{ post.date | date_to_string }}</span>
{{ post.excerpt }}
</div>
{% endfor %}
</div>
You are probably wondering about the paginator object used in the code above. Using the jekyll-paginate plugin, Jekyll automatically generates separate pages with link to older posts. This is called pagination in the world of Jekyll.
Interested?
If this short introduction to Jekyll sounds interesting, stay tuned for the next part about exporting your WordPress content.