Martin Pilkington occasionally mentioned the Jekyll static web site builder in his tweets, so when I wanted to start a new web site, I thought I'd give it a try, as I've been uncomfortable with having to back up WordPress sites in separate steps to get both the database and the image and movie assets.

Installing Jekyll

Make sure you have Xcode installed and its command line tools. Then just open Terminal and type:

sudo gem install jekyll

Creating a new site

To create a site, do

jekyll new

This creates a folder named in the current directory to hold the files for the new site.

Open the folder and in it the _config.yml file. Change the entry title: to what you want to call your new site, and url: to your domain name (in our above example, Feel free to change what few other settings there are, but you don't need to.

Two neat _config.yml tips:

  1. You can leave entries empty, e.g. the email: or github_username:, and they will just disappear, including their icons.
  2. You can make files and folders that Jekyll would usually skip (like .htaccess) by adding an entry like: include: [.htaccess, .well-known, _foo.xml]. You can also exclude files from copying/processing this way, e.g. exclude:

Testing the site

Jekyll includes its own web server. Simply type

jekyll serve

the site is now available under http://localhost:4000. The server will automatically watch for changes to the folder and re-build the site. If you still need to manually trigger a rebuild (e.g. to deploy your site without launching the server), just use

jekyll build

Adding your own pages

Like WordPress, Jekyll has pages and blog posts. Any file that doesnt start with an underscore is considered as a page. Be it index.html or Lets edit to describe our site, not Jekyll. Open it in a text editor.

The file starts with a section like this:

layout: page
title: About
permalink: /about/

called the front matter, followed by regular Markdown, as youd expect from a .md file. This section specifies the info that Jekyll needs about the page, and tells Jekyll to substitute placeholders in the file. You can leave this section empty, just its presence tells Jekyll to process the file. So its easy to create a new page. You can also make up your own settings here, if you want.

The ones in this example are standard ones Jekyll knows out of the box:

layout: specifies that the file _layouts/page.html should be wrapped around this file, and this files contents should be inserted where that file says contents. This is how Jekyll applies themes and shows navigation on each page.

permalink specifies the address at which the page will end up in the generated web site. So in our example, youd find this page at instead of at

title: is actually just a variable used by the _layouts/default.html template. Any variable you define can be used on the page by writing e.g. page.title . So if you added a line temperature: 40 Centigrade you could put it on the page as page.temperature .

Other interesting variables are categories, tags and published.

Blogging with Jekyll

Jekyll offers special blogging support. Mainly this just involves saving pages into the _posts folder and prefixing the file names with an ISO date, e.g. 2015-01-30-My First But it also has special functions to make it easier to link between posts in a stable fashion, and to generate lists of posts with teaser text etc. The Official Jekyll docs on blogging cover this well.

Importing from WordPress

Jekyll has support for importing from WordPress. First, install the importer:

sudo gem install jekyll-import
sudo gem install sequel
sudo gem install unidecode
sudo gem install htmlentities
sudo gem install mysql2

and then do what Jekylls WordPress Importer docs say.

I had an issue where Jekyll-Import would wrongly convert a constellation like

<pre>foo<br /><br />bar</pre>
<p>more directions<p>
<pre>foo<br /><br />bar</pre>

into invalid HTML (it would delete the closing </pre> on the first line). I fixed that by going into /Library/Ruby/Gems/2.0.0/gems/jekyll-import-0.5.3/lib/jekyll-import/util.rb and deleting the line that added “pre” to the alltags list.

If you’re on DreamHost, note that you need to go to “MySQL Databases” in the Panel, and there under “Database(s) on this server:” click the user name under “Users with Access” and enter your current IP address under “Allowable Hosts” before you can run this as that user. In this section you can also look up the (randomly generated) password DreamHost’s One-click install may have given your database.

Then go to “Hostnames for this MySQL server:” again and click “phpMyAdmin” behind your server’s name and look up what prefix DreamHost used for your database. The example in the Jekyll importer’s docs uses “wp_” but DreamHost adds a random element like “07foo_” (e.g. “wp_07foo_posts” instead of “wp_posts”).