I’ve just redone my website using Jekyll. It is now completely static. No PHP, no database, nothing like that.

Why did I do this?

  • It’s quite soothing knowing that all my content is version controlled.
  • I am now nigh-immune to traffic spikes. I was using caching with WordPress before, so it had never been an issue even when I was on the HN frontpage, but there’s some peace of mind in it.
  • WordPress had a history of security bugs which wasn’t comforting. Since nothing on this new site is executable I feel pretty secure now.
  • My site is now ridiculously flexible. Jekyll forces almost no structure on you, leaving you free to change things around as you please.

I’m happy with the end result, but the process of getting there was not without pain.

The initial difficulty came from Jekyll’s documentation being somewhat lacking. I found myself somewhat confused about minor details like “how does a layout work?”. After I’d cribbed that together by examining other sites posted with Jekyll, I discovered that the template data docs were inaccurate / misleading, implying the presence of a post variable which failed to exist. It turned out to be something that’s merged into page if you’re viewing a post.

I don’t completely blame Jekyll for this being opaque. Jekyll uses Liquid for its templating language, which claims to be aimed at designers… and I feel it would benefit from some sort of debugging mode that dumps the current scope for examination.

I resorted to reading Jekyll’s source, which cleared up a number of things. However, I view it as a bad sign that I felt I had to do this. Not that a command-line driven static website generator is ever likely to be a mainstream product, but still, it’s the principle of the thing.

Pagination worked, but was completely lacking in configuration. Since part of my goal was to have my URLs remain the same as they were in WordPress, I had to change this. I did so with a horrible monkey-patching hack of a plugin. Specifically, I made a copy of the pagination module from Jekyll’s core into my _plugins directory and selectively edited it to change the pagination urls.

In the process I noticed a bug in the core code, and submitted a pull request to fix it. So horrible monkey patching might at least pay off this time.

Also utterly broken was the related posts feature. No matter what, it always seems to think the most recent posts are the most related to anything. It’s possible that running with --lsi would have helped with this, via complex semantic analysis, but that takes forever and I’ve seen others complain that it doesn’t really help. So there’s more monkey patching going on via Lawrence Woodman’s related posts plugin, which I took and edited so it worked based on tags instead of categories.

One thing I haven’t fixed, which I’d like to, is making the automatic regeneration of your site during development / writing a lot smarter. Right now it notices a file has changed and so it regenerates every single bit of content on your site. This does mean that the live generated site always has recent/related posts up to date everywhere… but it’d be nice to have some sort of --quick option that ignored that stuff in favor of a faster development cycle.

Because of the utter staticness, I naturally cannot have my own comment system in use any more. So I’ve switched to Disqus, which adds commenting to the site via JavaScript. It feels sort of weird to be outsourcing a component of my user experience like this… but they seem to be trustable. Widely used, and their monetization plan is fairly transparent.

If you’re interested you can see the repo for my website on github. It contains, in its default / post templates, markup that’s compatible with any WordPress theme that’s based on Toolbox, which might be of use to some.

Like I said, I’m happy with how it turned out. I wouldn’t recommend this at all for a non-technical person, but if you want to dig in and get your hands dirty then Jekyll is quite workable.

Join the Conversation


  1. How is Disqus on the spam front? You’ve almost convinced me to switch to Jekyll, but the “having to outsource comments” thing is still a little scary.

    1. I’ve not seen any spam comments since I switched. I’d say that puts it at being slightly better than WordPress+Akismet so far, since I still got the occasional spam comment there.

    2. Oh, I forgot, you can use Akismet with disqus if you want, which means it’s at least as spam-proof as WordPress. More so, because the JS-based nature means you’re immune to all those crawlers which just hunt up comment forms and post stuff in them.

  2. Nice! I share your feelings about Jekyll’s lack of documentation. I’ve had similar pains when I switched to it last year. I, too, have found that looking at the source always helps.

    I’ve also recently switched to static comments, dropping Disqus. The technique employs a PHP file that accepts POST data from a form and emails a YAML comment. You then have to copy the email to a comment file under _comments, build and deploy (I intend to automate this at some point with a Rake task).

    I admit that the process is a bit involved, but at least you have total control over how your comments are rendered. The site is also faster (no JS) and you don’t lose your comments if Disqus goes out of business.

    My implementation was based on this

  3. you don’t need to copy the pagination plugin to get pagination like WordPress all you have to do is add this to your configuration file

    paginate_path: /page/:num

    That will give you nice pagination just like wordpress page/2/, page/3/, etc

  4. David, the related posts plugin from Lawrence doesn’t seen working with current Jekyll version – another user and I both got the same error message: “Wrong argument type class” etc. Would you mind sharing with us your edited version, which apparently is working?

    1. I’m afraid that the cruel truth of the matter here is just that I’ve not updated my blog since that plugin broke.

  5. Hi, having the same problem with my new blog, there are two posts, and the second one’s related posts shows the first one, even though they’re unrelated. 🙂

      1. Hi, yes I am. I am trying to use your code related_posts.rb – I’ve added it to the _plugins folder in the root of my local site (with comments added to the source to indicate your authorship). Hope that’s OK. Is that all I have to do, or do I have to change the existing pagination code in post.html which is:

        {% for post in site.related_posts limit:5 %}<br>       <li><br>        <h3><br>          <a href="{{site.url}}{{ post.url }}#disqus_thread" rel="nofollow"><br>            {{ post.title }}<br>            <small>{{ | date_to_string }}</small><br>          </a><br>        </h3><br>      </li><br>    {% endfor %}

        I havent’ commited this addition to the remote site yet, but I’m not sure what the code is trying to do (I’ve never heard of Liquid before and it just looks strange).

        1. Existing code in post.html looks fine. It’s basically what mine is doing, ignoring some of the variable names being different.

          It’s worth bearing in mind that the version of the related posts plugin that I adapted from Lawrence Woodman’s version relies entirely on tag similarities. So posts with no tags won’t have related posts.

Leave a comment

Your email address will not be published. Required fields are marked *