Git submodules are cumbersome to manage. In my opinion, git submodules are a sort of anti-pattern for Hugo (I know many themes suggest using git submodules). There’s a better way to manage your Hugo site’s theme: Hugo Modules.

Suppose you have a Hugo site and use a theme that supports Hugo Modules. I think the theme would need to require a minimum of Hugo v0.55.0. But, more features are available in later versions. Regardless, your mileage may vary:

Time to embrace Hugo Modules and leave git submodules to the dust bin of your site’s history.

Step One: Hate git submodules. You do? Good, me too. Let’s get rid of them!

Open your existing Hugo project that’s using a git submodule. Create a new branch. Then let’s rip out all the git submodule nonsense. This is highly destructive, be sure you’re not on your main git branch.

rm -rf .git/modules
rm .gitmodules
rm -rf theme*

Note: You’ll need to clear out the submodule from .git/config as well.

Step Two: Change Theme in config.toml

This section assumes you’re using TOML. If you’re using YAML, reference the Hugo docs for the right syntax. TOML users, your theme line should look like this:

theme = [""]

In a new section of your config.toml add the following (making sure to replace the appropriate fields in the example):

    path = '<USERNAME>/<THEME>'

Note the lack of https:// in the path. Also, the single quotes are important.

Step Three: Initialize the using modules

Next run these commands (I know these seem a little redundant but, I don’t think there’s harm in running them all):

hugo mod get -u
go mod tidy

NOTE: This is YOUR git repos URI

Last Step: Disable Post Processing in netlify.toml

Disabling post processing in netlify.toml is a good idea. This will prevent Netlify from breaking your site (SRI hashes).

    skip_processing = true

Commit, watch your build for errors, address any as they come up (I’d be interested in learning more if you have errors), and… PROFIT. Goodbye git submodules. We never liked you anyway.

If you notice something out of sorts here, please let me know or submit a pull request.


Related Content