Rafał Jońca

Over 16 years of experience in web development — both server (nodejs) and client (Vue) side. Senior software engineer in several projects.

See details
Rafał's photo

Newest blog entry
Updated Blog to Custom Hugo Theme

Static site generator behind this blog was last updated over 4 years ago. It was a Gulp 3 based system which also used Bootstrap 3. When trying to rebuild the site in 2020, it ended up that it is possible only with older Node.js and update to Gulp 4 all the existing generator is too much effort for such a small blog. So, I decided to switch to Hugo.

Why Hugo?

I checked Hugo many times in the past and even considered then using one of existing public themes. I haven’t found any theme that I liked and change existing one looked a bit complicated then. Current Hugo made a long way to make creating own theme from scratch a bit simpler, so I decided to move existing custom theme (used Handlebars templates) as the first step.

The other requirement was to maintain existing URLs for all important pages. With custom theme and several config changes it looked as something possible in oppose to premade Hugo themes.

The switch

Beginnings are always hard, but Hugo’s documentation and some samples of code from existing themes made the rewrite relatively easy. It is not hard to do everything part after part and because previous Handlebars theme was already using partials and was divided similarly, in most part change was related to the template language syntax.

The only downside of Hugo is that it uses template engine from Go language, which in general is fine (they are not reinventing anything), but is not very friendly to beginners when it comes errors. Because of built-in server with fast rebuild and reload, it is possible to do some trial and error changes quickly.

After the initial slowness of rewriting home page, all the other pages were created relatively quickly. I resigned from the archive section (with the about of blog posts here, it was not very usable). In the end I managed to get all other pages working more or less one day of work, which I consider a very good indication that Hugo is not that hard to learn, considering it was my first attempt to create custom theme. The final theme is not that customizable as the public themes, but it does not have to be.

Update libraries

When the theme worked and looked like the previous one, last step was to update other libraries like Bootstrap and cookie consent. Gulp generator used gulp-sass to build final CSS from Bootswatch Sass files with some additional changes.

I started to check the full toolchain required to do the same building for Bootstrap 4 and decided to use prebuild CSS for Bootswatch/Bootstrap. I still use Sass CSS to build my required changes in the theme, because I use Bootstrap variables there, but it only requires one library. I do not minify the custom CSS as it is short enough that it does not make much of a difference when compressed.

The changes necessary to update from Bootstrap 3 to 4 were not very big – including testing and preparations took only several hours. Main changes included: different styles for navbar or jumbotron, removal of panels (replaced by cards), removal of font icons (changed to svg ones).

Final thoughts

Maintaining simple personal website like this one requires some work to update it to newest standards. When in general it is not hard technically, it takes a lot of time to learn all the changes. In 4 years, a lot changed in the underlying libraries and because I do not actively work on the generator code, it was much easier to switch to existing generator like Hugo than make changes in 10 not that simple gulp content preparation pages.

Four years ago, I thought that the Gulp path will be easier, because I had full control of the code, but it also meant maintenance responsibility and Gulp 4 changed a lot in the details. Of course, Hugo may also introduce some incompatible changes in the next 4 years, but likely migration will be described clearly.

I plan to make one last change in the future, when the Bootswatch’s Cosmo theme for Bootstrap 5 will be out, I’ll migrate to it to be able to remove jQuery from dependencies.

See older blog entries