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.
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 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:
- You can leave entries empty, e.g. the email: or github_username:, and they will just disappear, including their icons.
- 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
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 ||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, 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. || 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 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 docs say.