Choosing a theme: best practices for long term maintenance

I’m creating a Hugo site that needs a fancy landing page (not a blog) and there are some great looking themes that require little configuration to achieve a good looking landing page (Syna, for example).

But these themes have a lot of customization like custom partials and js files.

These themes usually do not work on a default Hugo install.

I’m worried that if I choose one of these themes, future Hugo updates will require some work to keep the theme working. Should I use a ‘minimalist’ theme (hyde) instead of a fully fledget theme (Syna, Navigator). A minimalist theme will require some work to achieve a fancy landing page.

The fact, that Hugo has version numbers starting with 0 means, that it is under active development and things can change between versions (not the smaller ones, like 0.50.1 to 0.50.2, but the bigger ones like 0.50.x to 0.51.x). There is no “best practice” to keep a theme maintained for the long term. You always depend on the theme’s developer.

What you CAN do is the following:

  • take note of what version of Hugo you are using
  • try to update every now and then (3 to 6 months is a period where many new features come in) and see if “it” still works
  • if not, either FIX the version of Hugo to the one when it worked and keep working with that version (on Netlify, for instance, you can set the used Hugo version via netlify.toml) or find out how to fix the issue and fix it.

I have successfully done some pages for customers where I once a month just run a rebuild to see if everything looks the same or if any errors come up and fix them accordingly.

Another good way would be to create your own theme - you would know what features you use - but that might be out of your knowledge or time.

So if you have a simple landing page structure without much blogging components then follow the list above and you should be good.


The team who maintain the themes repository are working really hard to ensure all themes listed at work with the most recent version of Hugo.

However, as @davidsneighbour said, Hugo isn’t yet at a 1.0 release, and so new versions of Hugo can break things. They’re normally not that hard to fix…but if the theme owner doesn’t fix them, you may need to get your hands dirty!

1 Like

Thanks. I tried a lot of themes and some of them:

I’m still thinking about this issue, if I should develop my own theme or use one of the already created good looking themes that require some particular content structure.

I think that all themes listed at should work with the default Hugo (not Hugo Extended) and with the Hugo Basic Example site. Tests could be automated.

This will be good for the growth and adoption of Hugo.

Those are required before a theme is included in the themes showcase: hugoThemes/ at master · gohugoio/hugoThemes · GitHub

Good! What should a user do when she tries a theme using the Basic Example site and the theme breaks the site? Should the user report it to the team who maintains the themes repository?

Well for the first point it is required that all SCSS/SASS resources are generated and committed in a theme’s repo, so that the end user does not have to use Hugo Extended.

For the second point, it is not possible for all themes to work with the Hugo Basic Example structure that is aimed for a typical blog. Themes that require their own structure and site parameters are usually specialty themes meant to be used for other use cases like portfolio, documentation, e-commerce websites etc.

That is not needed. Each theme comes with a README and typically the author points out whatever requirements there may be.

If you encounter issues with a theme, it is advisable to ask the theme author directly on GitHub.

I see. Thanks.

So, there are 2 things:

1- SCSS/SASS: I understand, but actually some listed themes just don’t work without Hugo Extended.

2- Content Structure: OK. So it is not a requirement for a theme to work with . Themes can use their own self-contained Hugo site in /exampleSite/ as stated in

Which themes have you come across that don’t work with the basic version of Hugo?

I’ll double check again and let you know, probably tomorrow. (I tried a lot of themes) and I’ve installed Hugo Extended now, so I’ll have to uninstall it and install basic Hugo.