Hugo Themes

calendar Feb 12, 2022 · 6 min read · Hugo  ·
Share on: linkedin copy

There are tons of themes available for Hugo, take a look at jamstack and the Hugo’s own page and there are plenty to play with. The different themes are sutilable for different sites, for instance geekblog is a good blog site theme, Resume A4 could be a good personal portfolio site and showcase could be good for recipes. I think that choosing a theme is about knowing what your site is going to be used for and also seeing what features a theme has available.

Downloading a new theme

It’s easy to try some new themes to see how the GitHub pages may change. I wanted to try a few different themes so I decided to try the different ways of adding the themes too. Below are the details of how I added each theme and a exploration of the pros and cons.

Adding the theme directly via a download

This is the easiest way to add a theme:

  1. Find the repo for the theme, for example the hugo-coder theme
  2. Download the source and unzip it in the themes folder.
    Direct code download

This is a very simple way to add and test themes and is easy to reverse as reverting is a case of removing the theme folder.

One downside of this approach if used long term, is that applying any updates for the theme is a manual task, firstly finding the source for the theme then overwriting whatever already exists. Also, the theme files have to be stored in Git else configuration to use the theme will break the site.

Adding the theme directly via a clone

This is also a fairly easy way to add a theme:

  1. Find the repo for the theme, for example the hugo-theme-shell theme
  2. Copy the URL of the repo for cloning
    Repo url for shell theme
  3. Clone the repo in the themes folder of the hugo site:
    1git clone https://github.com/Yukuro/hugo-theme-shell.git

This is a simple way to add and test themes and is easy to reverse as reverting is a case of removing the theme folder. This method also allows for easy updating of the theme as getting the latest source is as simple as navigating to the theme folder and doing:

1git pull

One downside of this approach is the need to commit the theme files to Git else the configuration to use the theme will break the site.

Adding the theme by creating a git module

This is the method I see mentioned most often on the Hugo site and the theme sites themselves.

  1. Find the repo for the theme, for example the terminal theme
  2. Copy the URL of the repo for adding as a submodule
    Repo url for terminal theme
  3. Add the new theme as a new submodule, use this command from the main directory housing the Hugo site:
    1git submodule add https://github.com/panr/hugo-theme-terminal.git themes/terminal

Looking in ./themes will show that there is now a theme folder called terminal. We can also view the content of .gitmodules to see that the new theme has been added there:

1cat .gitmodules 
2[submodule "themes/terminal"]
3        path = themes/terminal
4        url = https://github.com/panr/hugo-theme-terminal.git

Updating a submodule is possible with this command so updating the site is as simple as using a clone:

1git submodule update --remote --merge

Submodules have some complexity with how they are managed and also build a little bit of complexity for anybody else working on the site. On first cloning the site the --recursive command should be used to ensure the theme is also downloaded. As with a clone, a submodule also keeps the git history. Removing a submodule is also quite complex. The site needs to be a git repo already before a submodule can be added, this depending on the setup this may not be desirable.

Adding the theme by creating a Hugo module

This is the most invovled way of adding a theme as there are dependencies to install but once set up the full power of Hugo can be unleashed.

  1. Install go - this is a one time installation as it’s a dependency for hugo modules.
  2. Initialise the Hugo site as a go module. From the root folder, the command for this site would be:
    1hugo mod init andrewfitzy.github.io
  3. Update the cofig.toml with the theme you’d like to add as a module, for instance to add the hugo-clarity theme add this:
    1[module]
2  [[module.imports]]
3    path = "github.com/chipzoller/hugo-clarity"
  4. Now start the hugo server, the theme will be applied.

As you can see, getting a theme set up as a module is a bit more invovled than any other the other methods but it does have some distinct advantages:

  • The theme will be incorporated automatically - no need to add theme files to source control or checkout recursively.
  • Getting used to modules will open up further functionality of Hugo

Configuring a theme

Direct download, git clone, git module

Unless the theme was added as a Hugo module, Hugo needs to be told the name of the theme to use in in confilg.toml. For example

1theme = "ananke"

or

1theme = "terminal"

Hugo module

If the theme has been added as a Hugo module, it’s simple to change between themes, for example:

1[module]
2  [[module.imports]]
3    path = "gitlab.com/neoteric-design/products/cosette"
4    disable=true
5  [[module.imports]]
6    path = "github.com/chipzoller/hugo-clarity"

This means 2 themes are available to the site, using disable=true for either of them will make the other theme be used… NOTE:- this will evaluate from first to last, so if there is no disable=true the first theme module encountered will be applied, cosette in this case.

Theme configuration

Once the theme is decided and set there may be a need to add parameters to configure the theme, these are generally specific to the theme and in the cases I’ve seen, will be detailed on the themes GitHub pages. For the terminal theme the configurations options are on GitHub.

Not supplying mandatory settings will lead to execution errors. For example, when I set my site to use terminal I didn’t supply the fullWidthTheme, or centerTheme params, when I tried to view the site locally I received a message like:

1hugo server -D
2
3Start building sites … 
4ERROR 2021/11/05 15:01:00 render of "page" failed: "/Users/andrew/site-source/themes/terminal/layouts/_default/baseof.html:10:23": execute of template failed: template: _default/single.html:10:23: executing "_default/single.html" at <$.Site.Params.FullWidthTheme>: invalid value; expected bool
5ERROR 2021/11/05 15:01:00 render of "page" failed: "/Users/andrew/site-source/themes/terminal/layouts/_default/baseof.html:10:23": execute of template failed: template: _default/single.html:10:23: executing "_default/single.html" at <$.Site.Params.FullWidthTheme>: invalid value; expected bool
6ERROR 2021/11/05 15:01:00 render of "page" failed: "/Users/andrew/site-source/themes/terminal/layouts/_default/baseof.html:10:23": execute of template failed: template: _default/single.html:10:23: executing "_default/single.html" at <$.Site.Params.FullWidthTheme>: invalid value; expected bool
7ERROR 2021/11/05 15:01:00 render of "home" failed: "/Users/andrew/site-source/themes/terminal/layouts/_default/baseof.html:10:23": execute of template failed: template: _default/index.html:10:23: executing "_default/index.html" at <$.Site.Params.FullWidthTheme>: invalid value; expected bool
8Built in 29 ms
9Error: Error building site: failed to render pages: render of "page" failed: "/Users/andrew/site-source/themes/terminal/layouts/_default/baseof.html:10:23": execute of template failed: template: _default/single.html:10:23: executing "_default/single.html" at <$.Site.Params.FullWidthTheme>: invalid value; expected bool

To resolve the issue I added this to my config.toml:

1[params]
2  contentTypeName = "posts"
3  themeColor = "orange"
4  showMenuItems = 2
5  showLanguageSelector = false
6  fullWidthTheme = false
7  centerTheme = false
8  autoCover = true
9  showLastUpdated = false

I now have a Hugo site with a different theme. This process can be repeated as many times as desired with different themes until the right one has been found.

I hope this has been helpful and inspires you to play with Hugo themes to find the right one.