Alberto Grespan

Hello, Hugo

August 13, 2017

Today I’m writing my first blog post generated by Hugo. Hugo is static site generator written in Go. A couple of months ago (maybe more) I decided to move my personal blog from Jekyll to Hugo out of curiosity. Yes, Hugo is indeed much faster and has a lot of great features, but it lacks some things that Jekyll provided (at least for me), such as ad hoc Sass integration, syntax highlighting with Rouge, and automatic deploys to GitHub Pages, either way I decided to dig into Hugo, read the documentation on some of the core parts, and used the migration tool to move my posts. It all went very well, the migration was seamless until I tried adapting my Jekyll layout into Hugo.

One of the hardest parts for me was understanding how the layouts work. Layouts are a bit complicated because in the documentation they are mixed up with themes. A theme is an “encapsulated” layout meant to be shared, while the layout is not. Started out with a theme and I did not managed to make it properly work, so I decided to fall back into a layout; after some research I felt I was on track using three default layouts, a baseof.html, a list.html, and a single.html. Before jumping it was necessary to read about Go’s templating language, which I found to be easy to pick up, flexible, and with good documentation, in the end It took me a few of hours to have everything working in this area.

Then I encountered another “sort of issue”, one I knew from the start. All of my Style Sheets are written in Sass and there’s no out of the box support in Hugo for it. I choose Sass long time ago as it made sense, it’s written in Ruby and was the de facto thing to do, also, over the years Jekyll-Sass integration became very good. This issue had a few alternatives, I end up picking in my opinion, the simplest one, one that did not made me install another interpreter/compiler, one that was fast, and that was sort of maintained. I decided on Wellington, it’s also written in Go, it uses LibSass (super fast), and the most important part is that my existing Sass compiled.

Something I really liked, although, it’s nothing special, is that Hugo allows you to use your configuration and front-matter in YAML, JSON, or TOML. My decision was to keep it in YAML, BUT, you can convert everything from YAML to TOML using the Hugo CLI command, that’ll let you experiment or migrate effortlessly, I tried it, it worked, but as I said, my decision was made.

Syntax highlighting was pretty easy to have in Jekyll with Rouge, but not really necessary, it’s a pretty thing to have. With Hugo I needed yet another dependency (python Pygments), so I decided to drop syntax highlighting completely, and with this I took a drastic change, I also dropped GitHub’s flavored markdown syntax in some of my posts in favor of plain old Markdown indentation.

Deployments was one of the main reasons I jumped very early on the Jekyll wagon, static site generation and GitHub Pages integration, something super awesome in 2011, that got better through the years. I’ve lost it, but things are not so bad either. I’m using the two repos now, one for hosting blog’s code and one for the generated output. You can read how it works in this excellent blog post.

All in all I’m very happy with my new setup, I have yet to try some of the many features of Hugo, such as Archetypes, Cross References, and Table of Contents. I got to experience a migration from one static site generator to another and see how compatible they are, and what a great fit Markdown is in this ecosystem. Hugo is FAST, at least an order of magnitude faster to generate my blog, but this was never a problem for me, I can install Hugo and Wellington through Homebrew making it easier to keep them up to date, documentation is good and they’ve recently made it better and easier to navigate. Even though I’m happy, not everything is perfect, I’m missing Jekyll’s Sass integration, and GitHub Pages push to master builds.

I hope this post puts my migration in perspective for anyone considering doing the same.