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 doesnt start with an underscore is considered as a page. Be it index.html or about.md. Lets 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 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 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 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”).