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

jenkins new example.com

This creates a folder named example.com 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, http://example.com). 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: Readme.md.

Testing the site

Jekyll includes its own web server. Simply type

cd example.com
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 doesn't start with an underscore is considered as a page. Be it index.html or about.md. Let's edit about.md 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 you'd 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 it's 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 file's contents should be inserted where that file says . 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, you'd find this page at http://example.com/about/ instead of at http://example.com/about.html.

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. Using Jekyll for static web site building on a Mac. So if you added a line temperature: 40 Centigrade you could put it on the page as .

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 Post.md. 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 Jekyll's WordPress Importer docsy say.

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").