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
- the config.toml is missing or has wrong info or
- you’ve activated a theme but not got the content folder hierarchy right
- 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).
all you have to do to activate a theme is update your config.toml with one more line
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
- Rename your old config.toml first
- Copy the config.toml from the
/yourtheme/exampleSite/folder to the top of your site
- Copy the contents from
- Copy the contents from
hugo server -Dagain
Hopefully now your theme is working and you can go back to customising your site.
if not … then one last step …
- Check and copy the contents from
/yourtheme/exampleSite/dataand copy into your
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