in Webdev minutes

Jekyll for the PHP User

You know the saying about if all you have is a hammer (every problem looks like a nail)?

Well sometimes CakePHP is too much tool for a job and even trusty WordPress is maybe a bit too much. What?!

TL and DR:

Jekyll is a static page generator written in Ruby. That means that the end product is not PHP or MySQL running on a server, but straight HTML/JS/etc. that’s ready to be uploaded to any server and maybe hooked up to a free CDN like I do with DreamHost/Cloudflare. When you realize that for a lot of basic blogs you really don’t need WordPress, it opens up a lots possibilities.

Granted, there isn’t the huge community that’s built up over the past 15 years, but converting a HTML template like 3rdwavemedia’s Velocity theme to a Jekyll theme is pretty straight forward, and pretty much the same as you would do if you where building a CakePHP app around a theme: chop up the parts and put them into Layouts, Elements or Cells (_includes and _layouts and _posts in Jekyll)…and no, as far as I know, there’s only Jekyll, no Hyde.


Well if you haven’t been keeping up with static site generators, this is going to sound a bit retro, but think about how many blogs there are mostly just serving up HTML from a simple database table. True, with WordPress (or any advanced Content Management System) there’s a lot more going on to assemble a page – and that’s why we have plug-ins WP Super Cache.

Well one of the guys, Tom Preston-Warner, over at GitHub wrote a Ruby program called Jekyll back in 2008, that took a different approach: put everything in text files with Markdown, then add the ability to tag the pages, handle layouts, plus some other goodies, and then compile out the whole site into HTML that can be uploaded to pretty much any web server and you’ve got the idea behind Jekyll and many of the other static site generators that came after it, including at least one or two, or three popular ones written in PHP. But Jekyll is probably still the best known and is easy to pick up even if you’ve never programmed in Ruby before – plus there’s tonnes of docs, themes and plug-ins out there to help you do many things you thought you needed WordPress for.

BTW: if you’re using GitHub Pages, you’re already using Jekyll already – and probably know all this already 🙂

So when I was working on a small side-project,, I decided to give it a try.

Getting Set Up

It’s pretty easy to install on Windows. Start by installing Ruby 2.0+, on your Windows or Mac system. Then head over to Jekyll and follow the instructions on the home page.

When you fire up http://localhost:4000 you’ll see their demo site. You can open up the folder and see basically all your files are in the main folder. There’s a few that start with “_”, these are special folders that hold specific parts that are assembled into the final site that lives in _site. One thing to remember is that anything in _site is wiped clean when it is re-generated (with the exception of folders specified in the _config.yaml file.)

Some Jekyll Tips:

  • In a lot of ways, Jekyll reminds me of how PHP websites would be written a long time ago: includes including other includes, there’s a lot more than that to it, but that can help you get started if you keep that in mind.
  • Pay attention to dates in the _posts folder; if you set the date to future date/time the post won’t be generated. Something to remember if Jekyll is not updating a page.
  • If you make changes to _config.yaml, or things don’t seem to be updating in the _site folder, you have to stop and re-start Jekyll serve. Jekyll is pretty smart though, if you change an included file, it usually know to update all the pages depending on it

The most interesting parts are in the _posts folder, for Jekyll is built for blogging and the pages are pretty simple, but you can get an idea about what’s possible by looking at one of them, or this, more or less, from the site I was building:

layout: post
title:  "Best Gyms in Vancouver" # sets a title variable accessible by post.title
date:   2015-12-22 19:02:54 -0500
permalink: /vancouver/health/best-gyms-in-vancouver
categories: [vancouver, vancouver-health]
tags: [sports, gyms]
active_link: vancouver # This is a custom variable I added, see next example 
dogs_rule: true # Ok, cats are cool too 
author: Zoltan


##Ron Zalko Fitness Centre of the page in Markdown goes here

Example of using a variable set in a post:

	<li class=" nav-item active"><a href="/">Home</a></li>
        <li>Current link: </li> <!-- display active_list, convert to "Vancouver" -->

Here’s an example of a layout:

<!DOCTYPE html>
<!-- C:\xampp3\htdocs\vancouver2toronto\_layouts\post.html -->
<!--[if IE 8]> <html lang="en" class="ie8"> <![endif]-->  
<!--[if IE 9]> <html lang="en" class="ie9"> <![endif]-->  
<!--[if !IE]><!--> <html lang="en"> <!--<![endif]-->  
    {% include blog-head.html %}
    {% include blog-header.html %}
    {% include footer.html %}

Example of printing categories:

{% unless page.categories == empty %}
   {% for cat in page.categories %}</pre>
     <li>{{ cat }}</li>
   {% endfor %} 
{% endunless %}

Printing the current year:

Copyright 2015-2016

There’s a lot more to Jekyll than this, but I’d be bascically just repeating what a number of excellent tutorials have already done. Honestly it took me about 2 hours to get comfortable with it.

Here’s some good links to get started: