Migrating Hugo From Git Submodule to Hugo Modules

Introduction #

This blog post talks about migrating from our legacy Hugo sites from Git Submodules to Hugo Modules.

Why Hugo Modules? #

Before I found out about Hugo Modules, I had issues upgrading my Hugo version from 0.136.5 to 0.148.1. I am not sure why but whenever I upgraded my module, the shortcodes cannot be selected correctly.s

As a result, I was stuck on 0.136.5, this results in the a lack of Hugo Updates (Learn more from the releases).

Other than the lack of updates for me, there are also more conveniences of using Hugo Module

1. Easy updates (Using hugo mod get -u to update all modules)
2. Quick to Configure

As a Git noob, I feel that Hugo Modules are easier to work with which prompted me to migrate.

Migration Steps #

Before migration #

Folder Structure #

├── config
│   ├── _default
│   │   ├── config.toml
|   |   ├── languages.en.toml
|   |   ├── menus.en.toml
|   |   ├── params.toml
|   |   └── taxonomies.toml
├── themes # My current theme in my git submodules
|   └── congo/...
├── ... # Others Omitted
└── .gitmodules

Submodule File #

[submodule "themes/congo"]
	path = themes/congo
	url = https://github.com/Jh123x/congo.git
	branch = stable

Config File #

baseURL = 'https://jh123x.com/'
theme = "congo"

# Other configs below
...

This is my directory structure before migration. I will be walking through the directory changes during each of my steps.

Step 1: Remove the git submodule #

# Removes the git submodule containing the theme.
git rm ./themes/congo

Remove the theme from the Git Submodule

├── config
│   ├── _default
│   │   ├── config.toml
|   |   ├── languages.en.toml
|   |   ├── menus.en.toml
|   |   ├── params.toml
|   |   └── taxonomies.toml
├── themes
├── ...
└── .gitmodules

As a result the congo theme should be removed from the themes directory.

- [submodule "themes/congo"]
- 	path = themes/congo
-	url = https://github.com/Jh123x/congo.git
-	branch = stable

The .gitmodules file should be empty now.

Step 2: Init Hugo Module #

hugo mod init github.com/<your_user>/<your_project>

Init the hugo module for your hugo repository.

├── config
│   ├── _default
│   │   ├── config.toml
|   |   ├── languages.en.toml
|   |   ├── menus.en.toml
|   |   ├── params.toml
|   |   └── taxonomies.toml
├── themes
├── ...
├── go.mod # New
├── go.sum # New
└── .gitmodules

After running this command, the go.mod and go.sum file should be created.

Step 3: Update the config files #

├── config
│   ├── _default
│   │   ├── hugo.toml # Renamed from config.toml
|   |   ├── languages.en.toml
|   |   ├── menus.en.toml
|   |   ├── params.toml
|   |   └── taxonomies.toml
├── themes
├── ...
└── .gitmodules

Rename your config.toml to hugo.toml.

baseURL = 'https://jh123x.com/'
# theme = "congo" # Remove this line

# Other configs below
...

Remove the theme configuration from the hugo.toml (Renamed from config.toml)

Step 4: Add module.toml file #

[[imports]]
path = "github.com/jpanther/congo/v2"

Create a module.toml with the contents above.

hugo mod get -u

After adding the module.toml, run the command above to update all the modules

├── config
│   ├── _default
│   │   ├── hugo.toml
|   |   ├── languages.en.toml
|   |   ├── menus.en.toml
|   |   ├── module.toml # New
|   |   ├── params.toml
|   |   └── taxonomies.toml
├── themes
├── ...
└── .gitmodules

After completing all of the steps your folder structure should look something like the above.

Step 5: Test the layout #

hugo server

Test if everything works by running the above command.

If it works you should see something similar to the image above after you run the command.

Conclusion #

In this blog post, we discussed about how to migrate from Git Submodules to Hugo Modules. For more information, you can refer to the useful links below.

Useful Links #

1. Official Hugo Modules Documentation
2. Congo Install Via Hugo Module