Emacs, scripting and anything text oriented.

Hugo Modules: Getting Started

Kaushal Modi

What are Hugo Modules and should you convert your Hugo site to be one?

This is a post in the “Hugo Modules” series.

2022-05-26Hugo Modules: Importing a Theme
2022-02-24Hugo Modules: Getting Started

The short answer to the second question is yes!

The Hugo Modules feature  This feature was added to Hugo back in July 2019 and it has become more stable and feature-rich with time. allows collecting different pieces of your Hugo site source from different repositories. Here each “piece” is a module. Those modules do not have to be just themes — they can even be parts of your site content.

From the documentation:

A module can be your main project or a smaller module providing one or more of the 7 component types defined in Hugo: static, content, layouts, data, assets, i18n, and archetypes. You can combine modules in any combination you like, and even mount directories from non-Hugo projects, forming a big, virtual union file system.

I find the Hugo Modules feature to be kind of like Git Submodules , or like a symbolic link aggregation scheme like GNU Stow but version controlled.

You need to install go in order to use Hugo Modules.

So you might wonder why you would want to go through that trouble ..

Why use Hugo Modules? #

Separation of reusable components
This benefit is same as that of using git submodules for managing themes. You might have separate repos for adding ATOM feed, another for adding search which you would want to reuse on multiple sites, and you integrate those in your main site repo as submodules. Hugo modules allows you to do the same, and then more (recursive module updates, printing dependency graphs, etc.).
Once a site repo is a Hugo module, it can start using the mounts feature.

Let’s call the main Hugo site repository the self module. Mounts are analogous to creating symbolic links  If you know what GNU Stow does, it’s kind of like that. from any file or directory in the self module to any file or directory in one or more of the imported modules (including the self module).

As an example, you might have a README.md in the root of your git repository. Using mounts, you can tell Hugo to use that same file as if it were content/_index.md  You can find the full example in github.com/bep/portable-hugo-links. , and now the same README.md serves as the content page for your site’s home page! 🤯

How to use Hugo Modules? #

1 Install a recent version of go #

The Hugo Modules feature is powered by Go Modules. So even if you don’t develop anything in go, you need to have a recent version of go installed (version 1.12  If you are using Netlify to deploy your website, go to the Deploy SettingsEnvironment, and set the GO_VERSION environment variable to 1.12 or newer. or newer).

As of <2022-02-24 Thu>, the latest stable version of go is 1.17.7. Download it from https://go.dev/dl/  Also see Installing go toolchain. .

2 Convert your Hugo site to a Hugo Module #

For your Hugo site to be able to use themes or theme components (like ATOM feed support, etc.), or even to use the Mounts feature, your Hugo site itself needs to become a Hugo Module .

Here’s how you initialize your site repo to be a Hugo Module. The following command assumes that you Hugo site repo lives at https://github.com/USER/PROJECT.

# cd /path/to/your/site/repo/
hugo mod init github.com/USER/PROJECT
Code Snippet 1: Initializing your site repo to become a Hugo Module

Here, github.com/USER/PROJECT is your Go/Hugo module name. This name does not need to be your git remote’s URL. It could be any globally unique string you can think of.

Note that “https​://” should not be included in the module name.

If all went well, a go.mod file will be created that will look like this:

module github.com/USER/PROJECT

go 1.17
Code Snippet 2: Example go.mod

Right now, the go.mod only contains your site’s module name and the go version used to create it. Once other modules are added as dependencies, they will be added in this same file  Coming back to the git submodules analogy, go.mod is similar to the .gitmodules file. .

Also, once other module dependencies are added, a go.sum file would also be created containing the checksums of all your module dependencies.

If you are managing your Hugo themes via git submodules, don’t worry! Converting your site to a Hugo Module will not break anything.

Example: hugo mod init #

I have a MWE repository called hugo-mwe to conduct small Hugo-related experiments, or play with a new feature, or attempt to reproduce a bug that I’d want to report. You can clone it and quickly try out the hugo mod init command.

git clone https://gitlab.com/hugo-mwe/hugo-mwe
cd hugo-mwe
hugo mod init gitlab.com/$USER/hugo-mwe
Code Snippet 3: Full example of initializing a Hugo Module

Closing #

In this post, I have given a brief introduction to what Hugo Modules are, and how you can convert your Hugo site into one. In the next post, I go through how to import themes as modules.

References #