I've been tempted to write a bit about Static Site Generators (SSGs) for a while now, mainly because I love them. I've been using Jekyll for various projects for a while now and I love it. The simplified hosting, higher security, and general hackability are just a few pros that make it worth it.
But they have also pained me, and after reading "The joy and pain of using a static site generator for private and client work" I thought I'd add in my own few observations from a Jekyll perspective.
Why would I talk about Jekyll specifically? It has a lot of pros that make it one of the most popular SSGs out there, and hence worth dicussing. Here are just a few:
Sadly not all is perfect and here are some of my main observations of working on a few Jekyll sites in small teams.
Most of you might not ever need any internationalisation but the day a client turns around to you and asks "Can we translate this one page to Spanish?" you will hate yourself for using Jekyll. Internationalisation is not standard supported and therefore a royal pain in the *** to do nice.
Not to mention that you can't serve the same content in different languages under the same URL depending on the user's cookie or locale. Forget about it, ain't gonna happen.
There are a lot of plugins for Jekyll and they're awesome. There's even a few for I18n, though I never tried them. Sadly non of them are supported by Github. Sure, you can compile your code client side, then push the compiled code (including the plugin generated code) to the server. This stops you from quickly pushing any mayor changes without using a laptop.
Jekyll is ridiculously simple. I think all you need is a config file and some HTML or Markdown and boom your site is there. But when your site extends beyond a few files you quickly start adding some folders: images go into
/images/, stylesheets into
/stylesheets/, etc. But what about pages? Use
foo/index.html? Store the images for that pages in
All of these decisions are easily made, but it does mean you need to explain every new decision to your colleagues, and it increases the technical debt when bringing onboard new developers.
I love Markdown but sometimes it can be such a pain. Especially when you want to go outside of the standard "headers, paragraphs, links" it can just be upsetting. Getting HTML inside Markdown to work in Jekyll used to (and probably still) require switching to a different Markdown parser, which wasn't supported on Github, etc.
To be honest this is a bit of a pet peeve with Markdown, not Jekyll. Often all I want to do is just add a class to something, either a header or a link. I often wished Markdown supported something like this:
This is a H2 with classname of foo
## This is a H3 with an index of foo ### #foo
In short, I think a few suggestions for the further improvements of Jekyll, Github Pages, and Markdown are at hand:
Alternatively I highly recommend using Middleman, another SSG that seems to solve some of the pain points described above.