This GitHub page uses Hugo as site generator. Specifically, it uses the hugo-profile theme. When I created this page, I did it from my Windows dev environment and it was all fine. But after cloning the page repository on my Linux environment, I never thought I would learn more about Git 😄
tl; dr After cloning my existing Hugo site repo, I couldn’t get the site building in my local environment. Spent about 2 hours troubleshooting the installation, yet the culprit was actually the theme being a submodule!
This is the error I came across when I ran the hugo server command:
WARN 2022/07/28 22:11:00 found no layout file for "HTML" for "page": You should
create a template file which matches Hugo Layouts Lookup Rules for this
combination.
This warning is complaining about missing template files. I was confused, as I already had this site working on my Windows dev environment. Seems like a warning, but it wouldn’t build the site. I would have call it differently, like fatal error or something punchier 😆
Let’s revise the typical Hugo folder structure.
hugo_site
|--- config.yaml
|--- archetypes
|--- content
|--- data
|--- layouts
|--- static
|--- themes
Under the themes folder, we find a folder that contains the theme used
by the site. Themes can be downloaded directly to this location, or as many
theme creators and Hugo tutorials show, themes are added as git submodules.
The theme is declared on the config.yaml file. As soon as the server is run,
Hugo will read the contents on the yaml file and build the site as per the
theme and options used.
I still consider myself a noob with git and Hugo, yet when I started to manually
inspect the site folders, I came across that the hugo-profile folder was empty.
Why?
A submodule is a way to keep dependencies tidy, as the submodule is a record to a specific commit of a repository. The official Hugo tutorial walks new users through a site creation on their Quick star guide using git submodules. Many theme creators follow this practice on their theme installation guides.
This being said, by cloning the page repo with the theme being a submodule, the clone operation does download this reference, but it does not download the external repository content. In other words, the theme files need to be downloaded again! 💥
To solve this, run the following commands:
$ git submodule init
$ git submodule update
After running the commands, the theme folder got populated with the theme files and Hugo could finally build the site. Since it’s only me working on my personal site, it’s alright to go through these steps everytime I clone my repo, but for larger collaborative teams, it may be painful.
Never a dull day here 😉