Hugo is great

Fast, instant refresh, markdown, templates, layouts and great configuration.

What more can we ask for?

I would say more clear guidelines on how to deal with Hugo themes.

Beginner’s difficulties with Hugo themes

The docs describe a sample quickstart site with a predefined theme. If we follow, we’re easily good to go with a new site. Yet, probably we would like to use a different theme.

So we go to https://themes.gohugo.io/ and find a lovely one. I’m using the Jane theme from xianmin.

We follow the instructions to download the theme inside the themes folder, start Hugo development server and open the browser to see… nothing of our content.

At this moment I would expect at least the initial post that we’d created during the quickstart to be displayed.

It turns out (after some time is lost forever), that each theme may use its own set of custom-theme variables and site configurations, without which it will not render any content. What we are supposed to do, and I couldn’t find it mentioned in the docs, is to overwrite our default site config.toml file with the one in the theme’s folder. We also need to copy the content folder of the theme and start changing that until we figure out how the theme works and what special extensions of the markdown language it supports.

My takeout from this initial experience with Hugo

tip

When using a custom Hugo theme downloaded from the internet, it’s best to use its config.toml and content files for the initial setup and from there start removing stuff we don’t need.

Cheers and probably bye-bye to Wordpress.