unit and acceptance testing, automation, productivity

Why I (shouldn't have) stopped blogging with Jekyll

It all started when I decided to add tags to my blog running on Jekyll and discovered that to do so I'd have to generate the static html manually because the plugin wasn't safe.

That "manuality" defied the purpose of Jekyll itself, publish new posts just with a push, so caught in a mix of annoyance and spirit of exploration I decided to look towards the Javascript scene.

Metalsmith promised to be lightweight and easy to use, so i jumped into a migration process that turned out not to be the good idea that I thought it was.

Meet Metalsmith

Metalsmith is a Node.js package for static website generation, based on the use of plugins.

The way Metalsmith works is simple yet effective, it reads all the files in a source folder, invokes a series of plugins that manipulate those files, and finally writes the results on a destination folder.

The team behind Metalsmith and the community have developed a vast array of plugins, making the task of creating a static website a matter of composing the right plugins.

Using gelatin-design as an example I rebuilt mokacoding one plugin at a time. I've released the result as metallo.js, the static blog generator you should not use.

The smith is still an apprentice

What I discovered by working on it is that metalsmith is not a mature software at all, and it's core feature, the plugin structure is a bit fragile. The problem is that it's not hard to encounter a setup where a plugin parses data making assumptions on it, but those assumptions are wrong because another plugin has been added to the pipeline and changed that same data. I could find no documentation regarding this issue. The problem itself is not an easy one, how can a plugin determine if the assumption it's making are reliable, or how can a plugin inform the other plugins in the pipeline that it changed the data in a way that could cause unexpected results? As long as there are only and handful of plugins in the pipeline it's simple to spot the issue, but it gets harder the more plugins you use.

Of course I could have realised all this about the state of the platform by spending more than just a couple of minutes through the READMEs, and maybe checking out the issues as well... Facepalm.

But you're reading this blog post from a Metalsmith powered blog, so despite not being a piece of cake, blogging with metalsmith is possible. So why was it such a not so smart idea to drop Jekyll? The keywords are three: time, content and hosting.


Our time is limited, and we have to juggle it the best way possible. I spent way more time that I wanted working on metallo.js. Yes it was fun and a good learning experience, and yes I think I achieved the result of making my blog and workflow at least slightly better. But it took me longer than hoped, and I'm now left with a consistent backlog.

One word is very important in the previous sentence, hoped. Being a personal project I didn't do any planning, I just thought and hoped that it wouldn't take long. As we all know developers are the worst people to ask for estimates.

Fail! If I had planned a bit I would have set a timebox and a list of experiments to do before starting with the migration. Doing so I would have discovered that this approach wasn't what I actually wanted, while still having fun and learning... Facepalm, again.


Blogging is, or should be, about the content, not the medium! Even if this is a tech blog, the people that read this blog are interested in the content of the posts, not on the fact that they've been generated by parsing markdown file and rendered with zero code duplication thanks to the view templates. The time I spend on this blog should be focused only on making the content better.

Here's a message to all the devs that like me have a blog that they use to store some thoughts, and that like me couldn't handle the idea of using tumblr or medium because of the "i can write it better" syndrome. Forget about the medium, focus on the content!


Now for a less philosophical consideration. I'm lazy and poor, so I host my blog for free on GitHub. If you want to use GitHub to host your static blog than Jekyll is the way to go. It's the software they recommend and all the integrations an nice features are build for it. Embrace it.

This is why I shouldn't have stopped using Jekyll. But let's face it this blog is my playground and I'm gonna keep messing around with it! I've learned the lesso though, and I'll kept it in mind for the future!

Have fun hacking your planned and timeboxed next project!

Want more of these posts?

Subscribe to receive new posts in your inbox.