I have for a long time thought of changing the theme on the site as the one I used hadn’t been updated for over a year (hence the build warnings) and it didn’t feel quite as “crisp” as I wanted.
What I looked for when selecting a theme was amongst other things that it was recently updated, responsive and a bit more “crisp” than the one I had. Additionally I wanted to keep the blog focus, with a two-column style and the content in focus.
The Mainroad theme ticks these boxes, but I was a bit hesitated because I wasn’t sure I liked the black and red coloring scheme. Actually I’m still not quite sure I’ll keep it, but for now it’s fine.
If you’re used to Wordpress, the theme switch process is kind of similar. You install the new theme and hopefully your content appears. Then you customize. There are settings that needs to be changed, widgets or sidebars to configure etc. Hopefully you can configure most of it in the site configuration, but you should expect to do some tweaking in the Hugo templates as well.
I won’t go in to details on how to install a theme, check the documentation for that. But in short I added the Mainroad theme as a submodule, and as I did with the current theme I created a separate folder for the customizations I did to the theme. To use your customizations you put this customizations folder before your theme in the
theme config option
I found that there was quite a few customizations to do to fit the theme to my needs. Actually a bit more than I had in mind, but I guess when you’re first getting started one thing leads to another..
Customizing the theme
You could do some of these in the layouts folder in your blog directory structure as well, but I find that a lot of these customizations are theme specific so for me it makes sense in having them in a separate folder under themes.
I’ll mention a few of the customizations I did next, but I will point out that I created a separate Git repo for my customizations so technically I have added it as a submodule.
The main customizations I did to the Mainroad theme:
I use the Cookie consent banner from Osano. I have added a reference to the CSS stylesheet for this to the
_default/baseof.html file, as well as a referene to a
I guess I could have added this through the custom css and custom js config options in config.toml.
The Mainroad theme supports a few metadata options for posts already and you can configure these through the
post_meta config option in
What I found missing was the Reading time and the word count. So I added my own
reading.html in the
layouts/partials/post_meta folder where I put in the Hugo variables for the two. The theme picks up the files in this folder and you configure in the config option.
I decided to display them in their own div inside the post meta section and used the
display: table style
You can override which parts of the metas that will be displayed on individual pages in the front matter which is nice.
However the post_meta is also used on list pages and thereby the home page. With all the default metas displayed that cluttered the home page so I created my own config parameter in config.toml for where I can control which metadata parts that are displayed on list pages, and used this in the summary.html partials file instead of the original post_meta option.
This was one of the biggest drawbacks to the theme and why I started customizing it in the first place. I wanted the ability to show a sharing section in my posts where a reader can share the post on a social platform or by email.
To fix this I created a
sharing.html partial which I added a reference to in the same section that displays tags in the
_default/single.html page so it will be added to each single page. I also created a config option to turn the feature on/off in config.toml.
As I did in my original theme I added a line at the end of each post that displayed the Last modified date as well as the commit message. Although the Last modified is displayed in the post_meta section described above I still added it to the end so I also could display the commit message.
Another thing I recently configured in the original theme was to display Related content. This is also added to the
On my site I multiple widgets in the right sidebar. The Mainroad theme supports a few widgets, but I did a few changes here as well. As with the post_meta section you can add more widgets by adding a file in the
layouts/partials/widgets folder and then control which of them you want to use through the
Params.sidebar.widgets config option. It can also be overridden on specific pages which is nice.
I added a widget for displaying badges, in my original theme I had a lot of badges from the different certifications I hold. In this theme I currently only display my vExpert badge.
I also added a widget for a “About the author” section where I use the Author details from the config options.
The final widget customization is a tweak on the taglist widget which comes with the theme. I have used a lot of different tags on my site so the list got quite long. To control this I added a config option for a minimum count on the tags to be displayed and added a filter on that in the
layouts/partials/widgets/taglist.html. Currently I’ve decided to not display tags at all, but I’ve kept the customization.
I also added some style tweaks to support a few of the customizations. The custom stylesheet needs to sit in a folder relative to you site config so I had to add it in the static folder. Ideally I would have wanted to have it in the theme folder to keep all theme customizations separate from the content.
I spent a great deal of time on these customizations, and it was a few more customizations than I initially wanted to do. But luckily the theme is quite customizable.
A bonus is that I got back into Hugo which I find quite fun to work with.
I might do a pull request on the original theme for a few of these customizations, but if you want to check them out, or even use them already you can check out my Github repo.
Thanks for reading.