Get Started with Hugo - Changing Themes and Config Issues

I’m new to Hugo, the fast and brilliant static site generator (SSG). But switching from WordPress, had me baffled at how hard themes are to change and the issues it causes.

The Hugo server will spit out garbage when

1. the config.toml is missing or has wrong info or
2. you’ve activated a theme but not got the content folder hierarchy right
3. you’re activated theme has custom code, layouts that needs to be moved.

This is post covers how to fix these errors …

Getting Started with Hugo is easy … once installed, you need type one command.

hugo new site blog

and then you’ll see

Congratulations! Your new Hugo site is created in /Users/damien/Dev/blog.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Congratulations … the hard work is done.

1. Problems with Config.toml

The config.toml file is important to the initial set-up of your site. It contains all of the customizations that theme developers want. The main problem this creates is the lack of any standard or consistency between theme publishers and how the config file is laid out.

Each theme will have its own config.toml - so rename and backup your config.toml before you change to a new theme.

Swapping Hugo Themes is easy as changing config.toml

There isn’t a standard template or consistency between theme publishers. In fact a basic config.toml has 3 lines (without a theme).

1
2
3

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

all you have to do to activate a theme is update your config.toml with one more line

1
2
3
4

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "theme name"

then you’ll run hugo server -D and go browse your localhost site to hopefully find things are working.

Wouldn’t it be great if this were true. Here, I’ll add: wouldn’t it be great if config.toml was split into 2 files - between Theme and Site Config.

2. Problems with Content folder and Hierarchy

Themes can have different content hierarchies or naming conventions one may use blog another posts - this will break your site

Solution - Copy Config.toml and folders in Example Site

This is when you realise that you can just copy the Example Site into your site structure

1. Rename your old config.toml first
2. Copy the config.toml from the /yourtheme/exampleSite/ folder to the top of your site
3. Copy the contents from /yourtheme/exampleSite/content into your content folder
4. Copy the contents from /yourtheme/exampleSite/static into your static folder
5. Run hugo server -D again

Hopefully now your theme is working and you can go back to customising your site.

if not … then one last step …

1. Check and copy the contents from /yourtheme/exampleSite/data and copy into your data folder.

If you don’t know Git, don’t use it to install themes

If you don’t know what Git is, or how to use it - then just download the theme and unzip the file

Even if you know Git … know the difference between Git Clone and Git Submodule Add - because, you will want to tinker and make your own changes to theme. And things will fall apart when you can’t commit and get an error like (from the Github Desktop Client)

Commit failed - exit code 1 received

see also … https://github.com/desktop/desktop/issues/4432

(which is fixable error - HT create a branch) … contact me and I can suggest a fix.

Did you find this helpful? Please let me know

Meet the author

Damien Saunders
An experienced management consultant and business leader interested in digital transformation, product centred design and scaled agile. If I'm not writing about living with UCTD (an autoimmune disease), I'm probably listening to music, reading a book or learning more about wine.
Find our more about me.