In an effort to resurrect my long neglected blogdown site, I decided to switch to a new theme. It is possible to use blogdown::install_theme() to get you started adding a new theme. But I wanted to do the update manually and then start to modify the theme to suit my needs. For R coders sometimes other languages and interacting with HTML and CSS can be intimidating but the results are very satisfying. I also think that tools like rmarkdown and shiny have forced us to know enough about web languages to work things out. This post is a record of the steps I took to change to and then modify a new Hugo theme, plus some of the small gotcha’s I encountered along the way.

First find a good theme

On the Hugo themes website there are almost 300 to choose from. The themes website is well designed so it is easy to filter and sort to find the theme you are after. Make sure you find one with good documentation and an example website for you to better understand how it all fits together. Not all documentation is created equally so it is worth taking the time at the start to work through it.

Another thing to remember is that themes can have different requirements for structuring your blogs content. So also check the example website’s structure to assess how much effort is required to adapt your site.

In my work life I generally have to use standard corporate themes. My previous theme was the wonderful future imperfect but this time I wanted to try something darker and something good for displaying photos. I also wanted a theme that:

is responsive and looks good on a phone
is good for displaying photos
has a good simple search function
displays tags nicely

Eventually I decided on the stack theme by Jimmy Cai. Some extra features that clinched the deal were:

ability to toggle between light and dark themes
local search
PhotoSwipe integration
an archive page template
no built in JavaScript or CSS frameworks

This last point, I hope, will lead to less conflicts when adding htmlwidgets to posts.

Import new theme

To import the theme I just followed the documentation and imported the theme using git clone before setting up the theme as a sub-module.

git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

These are the usual instructions for adding a theme. But adding the theme as a sub-module is optional. You will need to make some changes to the contents of the theme and you will also want to keep track of these changes in git. Using the code above the sub-module points to the original source, but you may not want to push your changes to this repo.

After a while I removed the sub-module and added the theme to the sites repo. To do this you need to use the git deinit command but you also need to delete cached files from the git repo. I did this based on a Stack Overflow answer which is copied below.

mv themes/hugo-theme-stack themes/hugo-theme-stack_tmp
git themes/hugo-theme-stack deinit themes/hugo-theme-stack
git rm --cached themes/hugo-theme-stack
mv themes/hugo-theme-stack_tmp subfolder
git add themes/hugo-theme-stack

Update the Config file

Now it is time to update your sites config.toml or config.yaml file. Remember we selected a theme that has an example website. So rename your old config file and copy across the one from the new theme example. Then you can go through updating the new config file based on the old one. With luck this will be enough to get your site running using blogdown::build_site() then blogdown::serve_site().

Update site structure

At this stage it becomes pretty obvious what is working and what is not. For me, the new theme had a different structure to deal with pages like about. Using the new config file and the structure of the example site I was able to adapt to this pretty easily.

The biggest issue I had was trying to update the page logo. This is just a .jpg file for both the old and new theme. It took a long time to realise that the new theme expected this file to be in the themes/hugo-theme-stack/assets/img folder when the old theme expected it to be in static/img. In both cases you refer to the file using img/logo.jpg, so I could not understand what I was doing wrong.

Exploring the Theme contents

It is worth having a good idea of the structure and the files in the theme. There will be lots of instances where it is best to make changes in the theme as this will cascade through the site. For example, I wanted to use highlight.js for syntax highlighting. This can be done with 3 lines of code:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/styles/a11y-dark.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/highlight.min.js"></script>
<script>hljs.highlightAll();</script>

Of course you can add this to each post, but if you add it to the theme it becomes available to all posts. This are where Hugo partial templates become really powerful. A partial is a small html template. On build all of the partials get joined together to form the full page. These small chunks are much easier to maintain and are often parametised and will vary depending on site and page settings and content.

In the themes/hugo-theme-stack/layouts/partials/head folder, there is a file called script.html. In the base theme the file is empty but is intended to be modified. There were also files called:

head.html
custom.html
style.html

I used the custom.html file to include all the links needed to add a favicon to my site. The svg for the favicon was created in Inkscape, then I used RealFaviconGenerator to convert to a favicon. This is the same service behind pkgdown’s pkgdown::build_favicon() function.

The last change to the theme I made (for now) was to add the read time for each article at the top of the page. Reading time is available in the Hugo page variable .ReadingTime. Hugo calculates reading time as (words + 212) / 213. After looking through all the files in the theme, I found that the themes/hugo-theme-stack/layouts/partials/article/components/details contained all of the page information such as title, description, and publish date. After finding the place to put the reading time I only need to add the following two span tags to get a book icon and the calculated read time.

<span>{{ partial "helper/icon" "book" }}</span>
<span class="meta__text post-word-count">{{ .ReadingTime }} min read</span>

The book icon was not a standard part of the theme. Luckily in the stack theme all of the icons have been generated using Tabler Icons and so it was easy create one that matched perfectly.

Add comments

In my previous site I used Disqus for comments but this time I wanted to try utterances. Utterances uses Github issues to manage comments. As my site is in a Github repo and is hosted via Github pages, it made sense to have one less account to manage. First the utterances app needs to be installed onto the repo where you want the comments to go. Then you can use the utterances configuration site to generate a code snippet that needs to be inserted into each page.

<script src="https://utteranc.es/client.js"
        repo="[ENTER REPO HERE]"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Again, the stack theme was a good choice as utterances is already part of the theme. All I needed to do to configure was add the code below to the config.yaml.

    comments:
        enabled: true
        provider: utterances
        utterances:
            repo: mrjoh3/blog
            issueTerm: pathname
            label: comment

Time to add content

And that, as they say, was that. The site is up and running with the new theme. I have made some minor changes to the theme and am quite happy. Really, where I did have issues I should have read the documentation more carefully. At the start of this post I said “pick a theme with good documentation and an example site.” While updating and modifying the theme I have been referring the the theme documentation regularly. It is always helpful, plus the example site meant I saved an enormous amount of time when restructuring the site to suite the theme.

Now that I am up and running, I just need to get to the hard part of adding content. Hopefully this post is a good start.