Last week, this site looked a bit different. For one, it wasn’t a blog yet. It was built with HTMZ (after starting out as just plain HTML), and it didn’t have much going on. The page was lighter than it is now. I only had to write one line of JavaScript, and about 100 lines of CSS to make it look decent. Everything was served locally since I don’t like pulling in content from CDNs that I can easily serve myself. No frameworks, no messy JavaScript, simple.
Back then I was toying with the idea of building a static site blog tool thingy, kind of like Jekyll, feature wise. But things weren’t looking good since I would’ve had to write a bunch of Python scripts to do what solutions like Jekyll do much better. Ever heard the saying “don’t bite off more than you can chew”? Yeah, the scope and complexity of building that tool/system would’ve definitely put me in over my head. So, not wanting to get caught up in that mess, and wanting to hit the ground running, I started looking for something that could do what I needed.
Before we continue, let’s take a moment to think about how to find the best tool for a job. For me, everything gets easier with lists. They’re straightforward and easy to understand. I try to make lists whenever I can because they help me figure out my priorities and make corrections, especially if I say the list items outloud. For example, when looking for a tool to help me build my site, I had a few must-haves in mind:
I don’t mind if the installation process is a bit of a hassle since I only have to do it once, but it’d be nice if it looked simple at first glance. I originally had installation at the top of my list because I wanted to get it done quickly and easily. But then I realized other things were way more important to me, like having an easy way to write posts, otherwise, the blog wouldn’t last long. I also wanted a straightforward way to deploy changes and posts. Most solutions are probably just a quick git push to update the site since it’s on GitHub Pages, but it absolutely needed to integrate with GitHub Pages. I didn’t want to mess with creating a separate folder and repo for the generated site and pushing that separately, or go through a bunch of steps in Github to have it served properly. Ideally, I wanted to push the whole thing, just as it is on my file system, with all the development files included, and have GitHub serve the right stuff without fiddling with it. And then there’s the RSS feed generation. I really didn’t want to have to install a bunch of plugins for that to work, it needed to be either built in or available as a single plugin.
After looking around for a bit I found a few options: Hexo, Jekyll, and Docusaurus
Right off the bat I started leaning toward Jekyll over the others. Just from the domain names (with the .io endings), I had a feeling Hexo and Docusaurus were built on top of some bloated, modern frameworks (but that wasn’t the case, at least not with Hexo). I checked out their sites, and Jekyll’s site was super simple, like I wanted mine to be. I was barely able to scroll, while the others had… a lot more going on. So, even though I hadn’t tried any of them yet, I was already vibing with Jekyll. But, I gave Hexo a shot first.
Hexo is a Node.js package, built in TypeScript, and I have to say, I liked it a lot. The setup was super simple, and it was my first introduction to static site generators. Hexo’s documentation is kind of bad, but there’s a lot of content on the internet, so I eventually found my way. I learned about layouts, front matter, variables (in the context of static site generators), and templates. The template stuff was a little tricky to get used to at first, but once you get it, there’s no going back to the old way of doing things. I was using EJS for templates, and while it could be confusing at times, I always found a way of getting things done the way I wanted. Overall, Hexo was a solid starting point, so I was pretty excited to give Jekyll a try next.
Jekyll is a Ruby gem, so naturally, it’s built in Ruby. The installation wasn’t as smooth as Hexo’s, but like I said before, you only do it once, so no biggie. I hit a little snag when I tried to set up the web server with bundle exec jekyll serve, turns out I needed to install a plugin called webrick to make it work. After that, it was up and running. Jekyll uses Liquid for templates, which was different and took some getting used to, but I think I liked it more than EJS… maybe. Jekyll’s structure and simplicity really clicked for me. It wasn’t too different from Hexo, but I think I liked it more this time because I had already gone through the initial learning curve with Hexo. By the time I got to Jekyll, I knew about _config.yml, layouts, templates, all that good stuff, so maybe it wasn’t a fair comparison. But overall, I definitely preferred Liquid, liked Jekyll’s project organization better, and then there’s the deplyoment and GitHub Pages stuff.
Jekyll’s GitHub Pages integration is super simple, just push to your repo, and you’re done. Hexo, on the other hand, has a few extra steps, or it makes you run a separate command, which I found kind of annoying.
Then there’s Docusaurus, which I didn’t even try since I read you need to write React components :)
When it comes to writing posts, both Hexo and Jekyll are pretty much the same. They make it super easy to write, style, and add whatever you want. I did like Jekyll’s way of naming and organizing posts better, but it’s not a big deal. Since that was the most important thing to me and they both handled it well, I didn’t let that sway my decision. Same goes for RSS feed generation, both use a single plugin, and I didn’t have a strong preference either way.
So, why didn’t I go with Hexo? Considering it’s powered by Node.js, which I’m more familiar with. I’ve never worked with Ruby or gems before. Well, I just liked Liquid more for templates, Jekyll’s organization made more sense to me, and I preferred Jekyll’s deployment and GitHub Pages integration.
Now, you might notice I didn’t dive into comparing popularity, bug reports, or documentation. In most cases, this doesn’t really matter unless there’s a huge difference, like one being way more buggy or immature than the others. But with these tools, they’re all pretty comparable: similar popularity, not overly buggy, and the documentation is hit-or-miss, like usual. You end up asking ChatGPT or searching for stuff anyway, which is just part of the process.
So, did I find the best tool for the job? Right now, based on what I need, yeah, I think I did. My needs might change down the road, maybe I’ll switch to Hexo, maybe not, or maybe I’ll try something completely different. But for now, Jekyll’s the best tool for the job.