Complaints about Jekyll

January 3, 2015

I’ve been using Jekyll for some time now and while I like the concept overall, I am really frustrated with a few things that I want to address.

First let’s talk a bit about Jekyll. Jekyll is a static site generator, which means that it takes a handful of files and transforms them to HTML so that they can be served statically by a web server. The power comes from the fact that you can do pretty much everything you’d do in a dynamic site such as using variables, templates, different writing formats such as Markdown, and still have the benefits of serving a static site.

Jekyll is of course not the only one nor the first one that has done this. It’s probably the most popular, or at least one of the most popular ones, because it’s used natively in GitHub Pages.

However, one thing that becomes evident once you try to use Jekyll for something more complex than just some development blog is that it’s clearly not a fully-fledged solution but rather a small hackish solution that has been growing since its inception in 2008. And you know what happens when hackish solutions grow, right? right? They become an unmanageable mess.

Let me just outline a few problems I have with Jekyll that really bug me:

  • Jekyll has been blog-aware since forever, but it was not until recently that it introduced the broader concept of collections. It is now possible to group articles or similar things into collections, but blog posts are still a special case within the system and not just another collection. This is evidenced by the prevalent naming convention of placing the date before the title, the fact that categories can be specified using folders, etc.

  • Jekyll has no concept of themes whatsoever, making it impossible to create a theme that can be easily installed either by just decompressing an archive or ideally by using a git submodule. This is frustrating when you want yo change themes, as you usually need to customize a lot of things for them to fit your needs.

  • It isn’t possible to generate a single file multiple times for example by using some variable as an iterator. This would solve a ton of problems: Internationalization, same data for both HTML and JSON (for AJAX) formats, etc. With carefully designed filters or options it would be even possible to use this to achieve arbitrary pagination. Speaking of which…

  • Pagination is only available for posts, and in a really strange way. In the most recent version it’s also broken, but let’s ignore that. Pagination is really complex and not very flexible. If you have used it you know what I mean.

  • The Liquid template engine sucks. It was clearly not designed for whole websites, but rather for small parts of larger websites. It doesn’t even have a way of creating layouts; instead Jekyll uses the content variable to insert the child content.

  • There are too many ways of creating pure data, and yet they’re all completely different somehow. You can:

    • Create a collection, which will be available in site.collection with all metadata and the contents. You don’t even need to render a collection, so this is pure data.
    • Create a data file inside _data/, which will be available in You can use directories too, so nesting is possible.
    • Add an entry to _config.yml, which will be available at site.watever directly. This is nice for site-specific things such as the title, description, author,etc.

    This is probably the weakest point on the list because it actually makes sense. It just bothers me that they’re all basically the same thing and yet treated so differently.

  • I don’t have much experience with this, but I have read it around: Plugins are a mess. I’ve read they are planning to re-write the whole Jekyll codebase and this is something they want to address.

  • Because it’s used nativaly in GitHub Pages, Jekyll tries too hard to ignore an already static website. That is, if you use Jekyll to build a static site that doesn’t know anything of Jekyll, you essentially get what you already have. For this reason, a file is completely ignored unless it’s in a special directory, a plugin has been instructed to do something with it or it contains YAML front matter. This is nice most of the time, but it’s also annoying in certain situations, in particular with SASS files.

That’s everything I could remember. Most of these are things I have stumbled upon on certain occasions and have frustrated me too much. Others are just “I wish this was simpler” things that probably everyone is thinking.

Of course, this is not just a rant. I’ve identified these problems because I’m in the process of writing a static site generator, and I want to be sure that it eliminates the things I am frustrated about. It is actually the whole purpose of the generator, but I’ll talk about it later.

If anyone reading this has another problem with Jekyll, please leave a comment! I’m genuinely interested to see what people complain about.