On Jekyll

That’s it! At long last, I’ve migrated my personal sites away from Wordpress. My blog and websites have been in need of a design overhaul for a long time, and as I was growing tired of the incessant and ever larger updates required by Wordpress and its plugins, I decided to switch to a static site generator.

Exit Wordpress, enters Jekyll.

For too many years, this migration and redesign has been put on the back burner because of client’s work, or heavy training for my “little hobby”: triathlon. I managed to find a little time here and there over the last year to make some way on a new design, but it’s only in the last few months that I really gave it a good push. With a few HTML templates and a clean CSS all ready, I only had to dig into Jekyll and start the migration process.

Why leave Wordpress?

1. I still remember the first version I used. Wordpress was a super small and very fast CMS to quickly publish posts with some image attachments. It was fast to use, easy to install on any LAMP stack, and fairly easy to maintain. That was before bloat arrived. In the past few years, I’ve had to deal with too many core upgrades, not just for my site, but also for the others I manage, and frankly, it’s been a pain every time.

   If you have a simple hosted blog on wordpress.com, chances are you don’t see any of this, but custom websites on WP can be a real pain.

   So, I was tired of fortnightly “security” upgrades where I had to re-upload almost a full website every time, and then go through the pain of checking that every plugin still worked happily with its neighbour and the new core code.

   Wordpress has its use and it’s probably serving millions very well. Not me. Not any-more.

2. I wanted a completely clean slate for my new site. Not another Wordpress theme migration whilst trying to find why a core method has been magically deprecated and that its replacement signature isn’t the same. I was going for a new design, a new structure, and more importantly, a new content structure. So starting from scratch was the best option to have a clean site on all fronts.

3. Then, I simply wanted to learn Jekyll. It promised to fulfil every one of my geek developer fantasies of being in control of everything, and all from the command line. I could finally go nuts on my “own” platform without having to reinvent the wheel from scratch.

4. It would also be a good opportunity to dig into some open source projects and maybe create and share some useful plugins of my own. This is what I did and some posts will come at a later date detailing my own plugins.

5. I wanted to see if I could increase the little SEO juice I’m getting by adopting a cleaner and simpler URL structure, and I didn’t see myself moving all this within a single Wordpress install without a lot of pain.

Blank slate and big expectations, then. Much like a brand new project.

What is Jekyll?

Jekyll is a static website generator. For those of you who still wonder what that means, it’s pretty easy: from a set of common files on your computer, jekyll will assemble a full website in plain html files. No PHP, no “request-time assembly”, no server logic. At all! Once written, the files aren’t changed by the server, and what clients request are only those files. That also means no database, and no dynamic code! Aside from the simplicity of the hosting setup, it most importantly means that you can completely do away with having them available in the first place, even in your local environment. All you need is a web server that dishes out plain HTML files, and that’s all. It also means a much faster website to serve to your clients.

I hear you say: “But without a database or dynamic code, all in static files, that sounds a bit like a step back, doesn’t it?”

You may be right for certain purposes, but in my context of a simple website, I didn’t need any dynamic code or a even a database. Actually, my content never needed this, and probably a lot of websites out there simply don’t need a database either. For most, it’s just a convenient way to store data, but there’s absolutely no need for it if you have something like Jekyll.

If you’re a developer and have written a few web pages, then think about that time all the way back when YOU started web development. If you are a total web developer novice, or even better, if you’d try to teach web development to someone new to it: how did / would you start? Probably with a basic html file. You’d probably write a few by hand, put them all into a directory, maybe upload them to the FTP server of a basic web host, and you’d have your first website.

Essentially, that’s what Jekyll creates for you: it creates static files like you’d do by hand. And by automating the generation process, it simplifies the whole thing a fair bit. But that’s the easy part of the story. Writing and hosting content for a site generated by Jekyll is dead easy, but unsurprisingly, there’s a bit of a journey to get there.

Configuration / personalisation

Before you write or deploy your website, there’s an absolute nerd part, which is the preparation of your “developer” or “author” environment, its configuration, and the plugins you may need.

There are tons of on-line guides for Jekyll and reports of how others did it, which has been a great help, but the very one thing that you’ll need if you want to get started easily, is to fork someone’s Jekyll repository. That way you will have something that works straight away and that you can start hacking around to make your own.

I started mine from Tim’s “kitchen” project, and the configuration+Rakefile already in there was a godsend to quickly get to speed. I have since added a lot to it and made it mine, but some utilities like the Rakefile haven’t changed much. You can also find the source of this very website on Github

If you want a migration guide, you can do like I did: follow the excellent one written by Paul Stamatiou and discard what you don’t need. I don’t have a special host other than Github pages, so I didn’t even look at the Apache stuff, and although my images are on S3+Cloudfront, I haven’t gone around automating the deployment process yet. The same goes for comments (more on that further), or special posts types.

The great thing about Jekyll is that it can be as simple or as complex as you want. As Paul mentions, beware of generation time for large sites, but do apply your own sauce to what you do.

If you want to go to ultra-basics, then the Jekyll website itself will give you some information. But trust me, after spending hours trying to figure out how plugins or other configuration parameters work, you’re much better of looking a code!

My own setup

One of the goals of getting rid of Wordpress for my own site had always been to get rid of my hosting package. Even if you can host a Wordpress install for free on excellent cloud platforms like openshift or Heroku, you will still have to maintain your platform more or less completely, or jump through some hoops to host a static pages website on a host that’s not really intended for it. With Jekyll, I decided to use Github pages for hosting, as recommended by many. All you have to do is push either the source of your Jekyll website or the generated static site to a special Github repository on your account, and it gets automatically deployed for you.

If you follow the first solution (e.g. you don’t generate your website “locally” on your local home machine), there is one thing that Github doesn’t do well: custom plugins. Obviously, for security reasons and to prevent the execution of rogue code on their servers, Github allows only a very limited set of Jekyll plugins to be used as part of websites generated directly on the github pages. Read this well: “generated on github”. That means that if you don’t generate your site locally, github will not generate your site if you need custom plugins.

However, you can still use your own plugins if you want, but you’ll have to generate your site on your local machine, and push only the result of that to your website’s Github pages repository.

If you’re still puzzled, there are also some handy guides for you to read!

That’s what I’ve done for my own setup, and that allowed me to write my own little plugins including:

• a “301 redirect generator” that creates a file pre formatted with all you need to migrate a Wordpress install: drop the result in a .htaccess of an Apache install and you’re good to go.
• a “comments mapping plugin” that takes a comments json file (generated from a Wordpress WXR file), and attaches them to the correct posts as an array to use in post generation templates.
• a “categories page generator”: based on the categories of each post (as written in their YAML Front Matter), categories will be available under /categories/[cat_name], including pagination options
• a “categories list generator” to generate an unordered list to display on your templates pages
• a set of helpers to automatically generate CDN urls for posts attachments.

On top of this I’ve added an RSS feed and a site map generator based on Paul’s work.

Deployment-wise, I wanted to use one common structure for two websites: this web orientated website, and another one dedicated to my triathlon passion. That means two static websites hosted on Github, but only one main repository that contains all the posts and jekyll source code, posts and specific configuration for each site being separated on their own git branches.

Overall, I now have three repositories:

• one main repository for the core Jekyll stuff and all the plugins
• one repository for the static files of my web-development / professional website
• one repository for the static files of my triathlon ramblings website

It’s very simple: the last two are being fed the result of “jekyll build” from within the main repository. As I am using rake tasks to simplify my life around Jekyll, all I have to do to publish a post on one or the other is switch to the correct content branch, write, commit, and execute “rake generate”. Everything else is taken care of automatically.

Again, follow this guide to mimic this setup.

If you’ve set-up your own website in a similar way, at this point, you should have something working well. However, if you’re hosting a blog, there’s one thing you may miss: comments!

Comments

This is a very contentious issue. As Jekyll will generate a static website, it means once online, there will be nothing that can respond to a form POST on your server. That means no “classic” comments. I mean “classic” in the technological, HTTP way here.

The only solutions you have so far are third party commenting systems like Disqus, Moot.it, Livefyre or others.

I’ve tried them, each to a certain degree of completeness, but Moot and Livefyre didn’t correspond to my needs, and after trying to import my comments from Wordpress into Disqus, having a debate with myself about leaving my content (comments on my content) with a third party, and reading numerous horror stories about transfers going wrong, I decided to NOT use Disqus in the end. In fact I decided to not use any third party comment system at all. I’ve deleted my Disqus account, and I transferred all my old comments to this new site, and I’ll build my own commenting system in the future, hopefully with spam control, and as one that should be available open source for self hosting so you can use it too.

Things I haven’t done yet

• Search: I’ll add a site search at some point. Unlike Tim’s fantastic web resources site, I don’t have the same link juice and my posts don’t appear on many search engines yet. So a little site search could help.
• Polish the publication process, especially around drafts and image uploads. At the moment, it’s quite an intensive manual process to create and upload images and galleries. Especially for my triathlon site where I sometimes have 40 photos attached to a post, all with their thumbnail versions. Hopefully I’ll come around to do a little plugin to help with image resizing, gallery generation, and upload to S3 / Cloudfront during the publication process through an extension to my Rake tasks.

Not for everyone

This is a nerd publishing platform. There is a lot to set up initially, and despite the best efforts of some, there are no “Jekyll for dummies” guides. You must know your way around code, around ruby, around your terminal and around git and Github. At a minimum.

But none of this is an issue for me: I’m a nerd, and I love it! It’s small, and I’m in control of everything locally, on my computer. The plugins I now use are pretty much all self-built, and the only thing that could go wrong in the future is my ruby version clashing with an old Jekyll install.

Other than this, the site generated is static, so there’s really nothing wrong in that!