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_user> and <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 config.toml files:

[module]
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy"

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.mod and 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 /tmp subdirectory:

# 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.