Hugo Theme Modification Practices

You’re probably familiar with the fact that Hugo has a wonderfully intricate and seemingly endless set of lookup order rules for figuring how to construct your website. This applies to layout files, themes, and all sorts of things in Hugo. Each type of resource has its own lookup order, and you could probably spend several years reading about it all if you wanted to.

However, it is fairly simple to understand some basic intended practices with regards to themes and theme modification in Hugo. The basic rule is, let the theme do its job unobstructed unless something actually needs to be overridden to be modified. Or, put another way, don’t just install a theme, copy the layout and style file folders into your Hugo files directory, and start chopping them up. This basically negates the entire purpose of having changeable themes in the themes directory.

This came to my awareness recently thanks to Vic Hudson, with whom I am constructing a podcast website for our friend Ronnie. I pulled in all the layouts from the theme into Hugo files, and he rightfully chided me for it.

In a very oversimplified manner of speaking, Hugo will go find the layouts and styles to apply in your active theme, which resides in themes, unless you have copies of them in your Hugo files folder or you have other layout or style files of your own making which you reference in your layouts and styles. You can therefore override things you want to change in a theme by just making a copy of a specific layout or css or scss file and putting that in the appropriate folder under the Hugo files folder.

If you have a git repo for your site, I strongly recommend installing your theme as a git submodule. This does two things: it makes sure that any theme changes come to you, and it makes sure to instill discipline in your theme modification hacking because now your theme is a living thing that can receive updates, not your own special little copy that you can bludgeon to death with poor practices.

Hugo Theme as git submodule

Even by taking care to only override or supplement where necessary, you’re still going to wind up with a lot of custom layouts, shortcodes, and other build-centric files outside of what comes with the theme, as shown below.

Custom layout files

Whenever you’re learning a new system, it’s really easy to get into bad modes of operation. While building this site, I copied all the layout and stylesheet files from the theme and pulled them into the Hugo files folder. As a result, I now have a theme that’s separated from the larger universal theme reality, and that has copies of files it doesn’t need to because I haven’t made changes to them. It’s a bad way to do things, and now I have to create a new git branch to start fixing the terrible ways I hacked my site theme for my own use.