Switching from Jekyll to Hugo

November 7, 2025

I switched from Jekyll to Hugo as my static site generator of choice recently. The only reason I have a Ruby environment is for this site, so moving from that to a single binary looked appealing.

I use a specific version of Hugo by downloading the binary directly instead of via a package manager. This was a tip I got from a similar post from Julia Evans. I liked the idea to be able to choose when to upgrade instead of my site breaking each time something changes with a new release.

Julia’s post also mentioned a way to import most of my Jekyll site with one command: hugo import jekyll. It moved the posts static assets (CSS, images) almost seamlessly, except for a few changes in the configuration and specific posts to render certain parts correctly. However, it did not import any of my templates, so the site wouldn’t render without adding a theme.

Themeing is one thing that has confused me each time I’ve tried to switch to Hugo in the past since I prefer making custom layouts. Hugo also offers a few base layout files that Jekyll did not, which took a while to get the hang of. Here’s the approach I took:

• I created a blank theme by running hugo new theme and looked up a post or two to understand the structure better.
• Then I simplifed the theme files further to get as close to my Jekyll layouts as possible.
• Then I moved the relevant directories (archetypes and layouts) from the theme folder to the root directory of the site, a structure that is familiar to me from Jekyll.
• Lastly I deleted the theme folder and ensured that my site still renders correctly.

The last set of changes I made were configuration changes, and the site was ready to deploy!

On one hand, the amount of configuration options in Hugo can get overwhelming, and the templating language is also confusing coming from Jekyll’s Liquid, making Hugo’s learning curve steep.

Where I prefer Hugo to Jekyll is when structuring the site files. Jekyll imposes a certain filename format and directory for blog posts, and any other collections/sections have to be configured differently. I reached a roadblock whenever I wanted to create other collections or sub-collections within the post collection. Hugo doesn’t impose such structure, and lets you define your own.

I’m looking forward to tinkering with Hugo more.