Hugo Git Submodules: Do Not Forget Your Theme!

The Problem

After cloning my Hugo blog from GitLab and adding a new post, I ran into a frustrating issue: hugo server would start successfully, but the site wouldn’t render any pages. Instead, I got a blank page with only the livereload script.

The build output showed warnings about missing layout files:

WARN  found no layout file for "html" for kind "term"
WARN  found no layout file for "html" for kind "section"
WARN  found no layout file for "html" for kind "taxonomy"

The Root Cause

When I cloned the repository, the theme directory was empty. Hugo themes are typically added as Git submodules, and by default, git clone doesn’t automatically download submodule content.

Checking the theme directory confirmed this:

ls -la themes/risotto/
# Output: empty directory

The Solution

The fix is simple - initialize and update Git submodules:

cd /workspaces/uclabdotdev/uclab
git submodule update --init --recursive

This command:

  • --init: Initializes submodules that aren’t yet initialized
  • --recursive: Handles nested submodules if any exist
  • Downloads the actual theme files into themes/risotto/

After running this, Hugo could find the theme templates and render the site properly.

Prevention: Clone With Submodules

To avoid this issue in the future, clone repositories with the --recurse-submodules flag:

git clone --recurse-submodules https://gitlab.example.com/user/hugo-site.git

This downloads the main repository and all submodules in one step.

Lesson Learned

Always remember: When cloning a Hugo site (or any project with Git submodules), run git submodule update --init --recursive if you didn’t use --recurse-submodules during cloning.

Your theme is just as important as your content!