Change From Beautifulhugo to Clarity Theme
Since I first started this blog, I was using a theme called BeautifulHugo. The theme was great and for the most part visually appealing. However, there were some changes I was hoping to see made to the theme that never really manifested. I had even contributed back some of my own changes, but it appeared the theme had been abandoned by it's creator. I set about looking for a new theme and stumbled onto hugo-clarity. Not only was this theme visually appealing to me, but I could see regular changes being made to the theme. Yes, a theme still under active maintenance!
In my own blog, there were a few customizations I had made to BeautifulHugo that I wanted to move into hugo-clarity. Fortunately, with the theme under active maintenance, these changes were quickly merged in when I sent up the Pull Request in Github. Here's the few changes I added:
|Changes Made||Description||How to Use It|
|Sidebar Disclaimer||Adds the ability to display a disclaimer (i.e. "my views are not my employer's) in the sidebar.||Documentation|
|Adding support for Utterances Comments||Adds support for the Utterances Github-based commenting system. It's similar to the commenting scheme used on docs.microsoft.com and helps filter comments by requiring the user is logged-in via a GitHub account.||Documentation|
High Level Migration Steps
Swapping Out the Theme
This time around, I added the theme as a Git Submodule. I went this route as I wanted to be able to periodically pull in updates to the theme, and I also wanted to force myself to stop making edits directly in the theme directory.
Lesson Learned: I ran into a few instances with Beautiful Hugo where I upgraded the theme and overwrote some changes I had made directly in the theme's directory structure. With hugo-clarity (and going forward with any theme I try), the theme can be customized using a directory structure of configuration files OUTSIDE the theme's directory.
With the theme set up as a Git Submodule, I can now pull in updates directly from Git (without having to do any fancy copy/pasting) and test locally with the hugo binary (
hugo serve) before publishing.
This was the most tedious part of the theme changeout. The themes used two totally different sets of TOML config files, and many of the configuration parameters had different names. To get started, I followed this process:
- Copied the
themes/hugo-clarity/exampleSite/into my main site's structure (
config/_default/params.tomlto bring forward old values (from beautifulhugo's
config.toml) into the new keys in the hugo-clarity site. Some important values include:
baseURL, copyright, DefaultContentLanguage, publishDir, author
config/_default/menus/menu.en.tomlto replicate the old menu structure from beautifulhugo.
My Example menu file is as follows:
1[[main]] 2 name = "Home" 3 url = "" 4 weight = -110 5 6# Submenus are done this way: parent -> identifier 7[[main]] 8 name = "About" 9 url = "/about/" 10 weight = -107 11 12[[main]] 13 name = "My Contributions" 14 identifier = "Links" 15 weight = -108 16[[main]] 17 parent = "Links" 18 name = "EUC TechZone" 19 url = "https://techzone.vmware.com/users/robert-terakedis" 20[[main]] 21 parent = "Links" 22 name = "VMware Tech Network" 23 url = "https://communities.vmware.com/people/rterakedis/activity" 24[[main]] 25 parent = "Links" 26 name = "VMware EUC Samples" 27 url = "https://github.com/vmware-samples/euc-samples/tree/master/macOS-Samples" 28[[main]] 29 parent = "Links" 30 name = "VMware EUC Blog" 31 url = "https://blogs.vmware.com/euc/author/rterakedis" 32 33# social menu links 34[[social]] 35 name = "github" 36 type = "social" 37 weight = 1 38 url = "https://github.com/rterakedis" 39[[social]] 40 name = "twitter" 41 weight = 2 42 url = "https://twitter.com/robterakedis" 43[[social]] 44 name = "linkedin" 45 weight = 3 46 url = "https://www.linkedin.com/in/terakedis" 47[[social]] 48 name = "rss" 49 weight = 4 50 url = "index.xml"
I'm fortunate that I didn't have a lot of pages, as one of the key steps in this was to reformat the front-matter on all my blog posts and pages. Fortunately, hugo-clarity has an archetype for new posts, meaning all I had to do was copy the front matter from that archetype into my current posts/pages and make some modifications. Fortunately, any time you use the hugo command to create a new page or post (
hugo new posts/my-first-post.md), it'll automatically fill with the new front matter.
As always, comments are welcome. My blog always seems to be a work in progress, but so far I'm loving the fonts and colors chosen by the theme's designers. I've also spent some time running this theme through Google's PageSpeed tests and it's far more responsive than BeautifulHugo. Hopefully you enjoy it as much as I do.