Fixing the Hugo Theme on Netlify Hosting?
This is a detailed blog post on how to fix the Hugo theme on Netlify hosting. I personally run this website with Hugo and I am impressed with the performance and configurations provided by the GoHugo as well as Netlify. If you are new to this setup then I would recommend reading this beginner's guide on - Hosting a website on Netlify.
Now let's talk about the issues which you might face while working with Hugo theme and Netlify. I have broken down each issue along with the troubleshooting steps so I would recommend at least going through the solution and identifying your root cause - (Note - For this blog post I will be taking hugo-clarity as my reference theme but the instructions and troubleshooting steps should work with all hugo-based themes)
- Update correct 'theme' name inside 'config.toml'
- Use git submodules for installing theme
- Check the Hugo Version you are using
- Update the correct baseURL inside 'config.toml'
- Conclusion
1. Update correct 'theme' name inside 'config.toml'
The first place I would start looking for is your config.toml and it is very much possible that you might have an incorrect theme name in your config.toml.
Let's assume you are using Hugo Clarity Theme for your static website. So the correct name which you should be updating inside your config.toml is hugo-clarity.
Where would you find config.toml?
There are two places you could find config.toml
- Under parent directory_(/your-project/config.toml)_ - Goto your static website project and in the project directory you will find config.toml. Here is a screenshot of my project structure for your reference -
- Under the directory_(/your-project/default/config.toml) The second place would inside the _(/your-project/default/config.toml). Most importantly this config.toml will override the entries of (/your-project/config.toml).
Here is a screenshot for the reference -
My Recommendation- Always work on single config.toml file present under _(/your-project/default/config.toml) because any value present inside this _config.toml(/your-project/default/config.toml) will override the other config.toml(/your-project/config.toml)
What value you should update- Make sure to pick the correct name of the theme and as for this blog post I am taking hugo clarity as my preferred Hugo theme so I should update the hugo-clarity inside my config.toml. Here is the screenshot of my config.toml
2. Use git submodules for installing the theme
The second probably cause for your theme not working on Netlify is that - You did not have git submodule configuration present inside your project.
Since all the Hugo themes are developed and maintained by other open source communities and maintained on GitHub, the proper way to use those themes is via adding them as a Git Submodule. In most cases, users prefer to use git clone rather and do not add the theme as git submodule add.
Although the git clone method would work fine if you are doing change locally onto your work machine but Netlify needs a submodule configuration to load the theme once you deploy your static site on Netlify.
Where to find the .gitmodules inside your project?
There are .gitmodules file which you should find inside your root project and if .gitmodules is missing then that would be the probable cause why your theme is not working on the Netlify
Here is the screenshot of my project structure containing the .gitmodules file -
How to add Hugo theme as git submodules?
Although GoHugo has really good documentation on how to add a theme as a submodule you can use the following git submodule command to add a Hugo theme as your submodule.
- First go to your themes directory.
1cd themes
- Use the
git submodule addcommand to add theme -
1git submodule add https://github.com/<THEMECREATOR>/<THEMENAME>
You need to replace the
3. Check the Hugo Version you are using
The third check which I would recommend is for the Hugo Version. GoHugo has a regular release cycle where they keep incorporating new changes into the Hugo static site generator and many of the Hugo-based themes do not support the old version of Hugo.
I would always recommend checking the GitHub repository page of themes and specifically the README.md for any explicit mention of the Hugo version.
As of now, the Hugo Clarity runs on the extended version of Hugo 0.91.0 or above, so make sure your Hugo theme is using the correct version of Hugo.
4. Update the correct baseURL inside 'config.toml'
In general, whenever we deploy a website on Netlify, we always point our custom domain_(https://www.my-custom-own-domain.com)_ so that you can easily access your website with that domain name.
When you deploy your Hugo static site on Netlify then it will give you some random URL to access your website. i.e. - https://relaxed-ramanujan-xxxxx.netlify.com. To correct that randomly generated URL you need to follow this guide on setting up custom domains with Netlify.
But in most of the cases, we miss updating baseurl property present inside the config.toml.
Update the baseurl with the correct domain name inside your config.toml
Here is a reference of the config.toml with correct baseurl -
1baseurl = "https://jhooq.com/"
2copyright = "Copyright © 2008–2018, Steve Francia and the Hugo Authors; all rights reserved."
3paginate = 10
4theme = "hugo-clarity"
5disqusShortname = ""
5. Conclusion
I hope the above points will help you to troubleshoot your Theme issue while hosting your website on Netlify. I composed all of the above instructions for troubleshooting based on my experience with Netlify. If you are new to static site development and looking to build your website then I would recommend reading more on - Which framework to choose for creating a static website?, Hosting a website on Netlify
Read More -