Moving Website to Hugo Modules
Hugo 0.56.0 introduced one notable feature called “Hugo Modules”. Hugo Modules allow you to add more flexibility to your Hugo project organization. Using this feature, you can import different modules that will implement one or more Hugo component types. For instance, you can use one module that provides layout for your website, and another one to add more shortcodes, etc. Moreover, this feature enables you to mount your own directories or files that are not necessary tracked by Hugo.
For my webpage, I use a modified “Academic” theme that has been recently renamed to Wowchemy. As a part of the rebranding, the author migrated it to use Hugo Modules. I have devoted some time to understand how Hugo Modules work and how to migrate my website to use this feature. This blog post is mostly a memo for myself, however, it may be useful for others as well.
Migrating “Academic” Website to Hugo Modules
First of all, we have to de-init “Academic” git submodule. You can do this using two alternative ways. Change directory to your website root, and run the following commands:
$ cd <website_root> $ git submodule deinit themes/academic $ git rm -r themes
Alternatively, you can de-init a git submodule executing following actions:
$ rm -rf themes/academic $ rm -f .gitmodules
Now, we are ready to start using Hugo Modules. Hugo Modules are built on top of Go modules package management system, therefore, to use it you have to install one of the latest Go versions supporting this feature on your computer.
At first, you need to
initialize your website as a new Hugo Module. Run this command (substitute
<your_project> with your data):
$ hugo mod init github.com/<your_user>/<your_project>
For instance, in my case this command looks the following way:
$ hugo mod init github.com/zyrikby/website go: creating new go.mod: module github.com/zyrikby/website
After the module is created, we need to import theme module. So as I am using “Academic” theme, I will use it as example. Add the following lines to the end of your
config.toml file. If you use multiple environments, you have to add these lines to all environments
[module] [[module.imports]] path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy"
theme = "academic".
Now, we need to update all Hugo Modules. Run the following command:
$ hugo mod get -u
After all these operations, two files should appear in your website directory:
go.sum. In my case, the file
go.mod contains the following data:
module github.com/zyrikby/website go 1.15 require github.com/wowchemy/wowchemy-hugo-modules/wowchemy v0.0.0-20200903212926-73d157ece01d // indirect
There are several command variants to update dependencies. I recommend to check them all, especially if you need to update theme to a particular version.
During the update, Hugo creates a local cache of downloaded modules. In my case, this cache is stored in the
# find /tmp -type d -name "wowchemy" /tmp/hugo_cache/modules/filecache/modules/pkg/mod/cache/download/github.com/wowchemy /tmp/hugo_cache/modules/filecache/modules/pkg/mod/cache/download/github.com/wowchemy/wowchemy-hugo-modules/wowchemy /tmp/hugo_cache/modules/filecache/modules/pkg/mod/github.com/wowchemy
After all these operations done, you can run
hugo serve to see your website:
$ hugo serve # add -e <env_name> if you use environments
If you host your website at
Netlify using configuration stored in a
netlify.toml file, do not set there the value of the
HUGO_THEME environment variable. If you have a line
HUGO_THEME = "academic" in
netlify.toml, remove or comment it, or Netlify build system will generate the following error:
Error: module "academic" not found; either add it as a Hugo Module or store it in "/opt/build/repo/themes".: module does not exist
Notes on Hugo Modules
Although from one side Hugo Modules feature adds a lot of flexibility to website creation, from another side this makes modification of a theme a lot more complicated. Indeed, before all theme files and directories were stored in a
theme/ subdirectory. If some modifications of the theme were required, I created an overlay coping and modifing corresponding files from the theme subdirectory. Unfortunately, theme data are not stored within the website data when using Hugo Modules, therefore, process of making modification is more complicated. The official documentation recommends to use
replacements of files and directories.
Personally, I do not use this feature. I rely on a local copy of the theme repository. I have cloned “Academic” theme repo, and I merge my modifications by comparing updated files with my current version. Maybe this is not the best merging strategy, however, currently it works for me well.