Change From Beautifulhugo to Clarity Theme

Background

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!

Contributed Changes

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:

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.

Moving Configurations

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:

1. Copied the config folder from themes/hugo-clarity/exampleSite/ into my main site's structure (/).
2. Modified config/_default/config.toml and config/_default/params.toml to 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
3. Modified config/_default/menus/menu.en.toml to 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"

Modify Front-Matter

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.

Closing Commentary

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.