Theme as a hugo module or theme as a git submodule?

Using Themes
1

I’m working on my theme, and I was wondering whether starting to use hugo modules for it or not.

The theme works because it provides an example site to work with, but I feel like importing the theme as a hugo module without making you able to see the files could actually be more confusing than using git submodules, especially if you wanna make changes to the theme itself.

Hugo modules pros

  • better version control (you can import a specific version of your theme)

Git modules pro

  • Easier to make changes to the theme, you can go check out the theme folder directly if something doesn’t work out correctly.
  • Git modules cons
  • you can’t link the submodule to a specific release commit so that your example site is linked to a specific theme version as well. I don’t think so unless you specify the hash when doing the pull of the theme (and I feel like this is a bit cumbersome).
  • If you update a submodule you update to the latest commit, not to the latest version of the theme.

I feel like making people download the example site from github and then git clone --recurse-submodules is not as much as a bigger step compared to downloading the examplesite with the theme module already imported, but having the latest version of the theme cloned with an older (pheraps not compatible) version of the example site can be confusing.

This can happen with hugo modules as well if you don’t specify the version in imports.

Essentially what I’m trying to achieve is version consistency across theme and example site, and I don’t know which of these workflows would be better for that. I also wanna make it very accessible for developers as well.

At the very least I think I shouldn’t make the site import the latest version of the theme module automatically but should package each version with [imports] of a specific version of the theme, or with the right git submodule.
I also wanna make users able to update the theme for quick corrections which are compatible with the example site.

Also considering the thing from a developer side of view, if someone wanna work on my theme is easier to have gitmodules than having hugo modules and then having to get the module (and disable the related mounts) to see changes locally.

With git modules I could make users download a version tag somehow (?), and developers simply cloning my repo.

Also honestly if a theme depends on a specific configuration that comes with the example site (like the variables in themes layouts), is there even a point in keeping theme and example site into 2 separate branches (2 different git modules). Should I transfer the configuration in the theme as well?

I’m trying to develop something that is easy to understand, therefore I wouldn’t want to have one config file in the theme, one in the site + one for each language if it isn’t absolutely necessary or doesn’t clear things out.

I can’t give users a packaged and ready to use example site without making it more cumbersome for developers to edit the theme, the theme files should come as well and should be connected to the repo somehow.

2

In the absence of additional instructions, I agree. But you could include something like:

To inspect the module components, run hugo mod vendor and examine the _vendor directory.

Instead of modifying files directly within the _vendor directory, override them by creating a corresponding file with the same relative path in your project’s root.

When you’re done inspecting the module, delete the _vendor directory. This is necessary if you want to update the module with hugo mod get -u in the future.

3

Hi thank you for the answer!

So how would I make people work on my theme with git if I use this vendor strategy?

Users can just get the theme automatically with the website with hugo modules, but what about developers? How can they work with git stuff and see live changes on the website?

I feel like using the theme as module could be better for users but worse for developers.

Maybe I would have to use both hugo and git modules? Or should I just stick to git modules?

4

Developers will clone your theme repo.

Neither git submodules or Hugo modules works for development.

5

I’m biased, but I would go Hugo Modules every day of the week. Only downside I see is that it requires Go installed.