🆙 Update Hugo Themes or Plugins

Learn how to update a Hugo-based website to the latest version of a theme or plugin.

Hugo’s theme/plugin management system is named Hugo Modules, based on Go Modules. This is the Go equivalent to Node Modules, the management system for Javascript based website generators.

Your themes/plugins are installed in Hugo’s hugo.yaml file (previously named config.yaml) under a modules section, or in a dedicated module.yaml file.

The version of the themes/plugins that your site uses is defined in Hugo’s go.mod file.

So the high-level steps to update a theme/plugin are:

• to check that the theme/plugin URL in hugo.yaml or module.yaml is up-to-date, matching the URL of the theme/plugin GitHub repository and any sub-folders
  • for themes/plugins greater than version 1, Go post-fixes the major version to the URL, such as <MODULE_URL>/v5 for a module on version 5
• to update the version of the theme/plugin in go.mod to match the latest release in the Tags section of the associated GitHub repository
• to apply any breaking changes described in the GitHub Release Notes of the theme/plugin
• update Hugo to the version supported by the new release of the theme/plugin

Need help? Join the Discord to chat live with the community.

TLDR

1. Head over to your website project in Github, click the go.mod file, and click the pencil button to edit it
2. Update the require statement to always get the latest main version of each module:

   github.com/HugoBlox/hugo-blox-builder/modules/<MODULE-NAME-HERE> main

   • Otherwise, to get a specific version of a module (recommended), replace main with a version from the tagged releases of the module. For example, the blox-bootstrap module has a modules/blox-bootstrap/v5.9.6 release which we can update to by replacing main in the example above with v5.9.6
   • Save your changes to the file by clicking the green Commit Changes button
3. Update your site’s Hugo version to a compatible Hugo version from the Release Notes or from the latest version of the template that your site uses
   • If deploying to GitHub Pages, edit WC_HUGO_VERSION in .github/workflows/publish.yaml - example
   • If deploying to Netlify, edit HUGO_VERSION in netlify.toml - example
4. Consecutively apply any breaking changes from the relevant Release Notes
5. Check that the latest deployment of your site is successful (otherwise click the failed build to view the issue)
   • If deploying to GitHub Pages, head to your repository, then click Actions and Deploy Site in the left menu to see the latest deployment log and check that it didn’t fail
   • If deploying to Netlify, head to the dashboard for your site and click Deploys in the left menu to see the latest deployment log and check that it didn’t fail

Join the community to learn when we release improvements:

• Star (and Watch) Hugo Blox Builder on Github
• Join the Announcements channel on Discord
• Follow @GetResearchDev and @GeorgeCushen on Twitter
• Subscribe to the blog RSS feed

Full Process

The update process consists of:

1. Preparation
2. Updating Modules
3. Migrating your content front matter and configuration by applying any relevant breaking changes

Preparation

Before updating Hugo Blox, it is strongly recommended to make a full backup of your website folder.

Then, record your current version, so that after you update the modules, you can apply any relevant breaking changes to the site configuration in the config folder and front matter in your content/ folder.

To find your current version, look in the go.mod file in your site folder where it’ll either be an exact version like v5.0.0 or it’ll be a specific build in the form v<dummy-version-number>-<date>-<build-number>. The first 7 characters of the build number can be cross-referenced in the commit log to check what development updates are available.

Note that if you installed a build in the main version rather than a specific release, then extra care should be taken (such as by checking the git log if you installed with git) as you may be in-between versions and some actions in the relevant release notes may have already been applied.

Update Hugo Modules

Update

Hugo uses the go.mod file to control which version of Hugo Blox Builder a site uses.

Open a Terminal (Command Prompt) and navigate to your site’s folder using the cd command.

To update all modules to the very latest (main) version:

For each module in go.mod run the command below, replacing <MODULE> with the module path in go.mod, for example github.com/HugoBlox/hugo-blox-builder/modules/blox-bootstrap/v5 for the Bootstrap UI module:

hugo mod get -u <MODULE>@main

Alternatively, to update each module to the latest official tagged release (e.g. v5.9.3):

hugo mod get -u

Migrate your content front matter and configuration if necessary by applying any relevant breaking changes.

Migrate Content

When you update Hugo Blox Builder itself, you can jump straight to the latest and greatest version. However, content migration requires consecutively applying any relevant steps from each release.

To migrate your YAML front matter and configuration, apply any relevant steps from the Breaking Changes section of each consecutive release note since the version you were originally on. If a release has no Breaking Changes section, then no changes are required.

For example, if you are updating from v2.4.0 to v3.1.0, then apply the breaking changes for the relevant consecutive releases. In this case, that would require first applying the breaking changes from v3.0.0 and then applying the breaking changes from v3.1.0.

To help migrate content to be compatible with new versions of Hugo and Hugo Blox Builder, there are some scripts available in the Awesome Hugo repository which you might find useful.

Troubleshooting

Check out the release notes for the consecutive version that you are updating to, paying attention to the Breaking Changes section. You can check which version you currently have, refer to the Preparation section above.

If there are any issues after updating, you may wish to compare your site with one of the latest templates, such as the Academic Template to check if the file structure changed, any YAML settings changed in the configuration files (i.e. all files in the config/_default/ folder), or any options changed in the front matter of content files (i.e. files in the content/ folder).

If you overrided any Hugo Blox theme files by using Hugo’s inheritance principle then these may cause conflicts after updating. For example, if you have modified theme files in a layouts folder, your modifications may have become out of sync with the theme they were copied from. Consider temporarily removing your overrides and checking if the original file(s) that you are overriding have changed in any way and require syncing with your custom version of the file(s).

Solve common issues with the Troubleshooting Guide. If the issue is unresolved, feel free to reach out to the community on Discord or the Forum with your GitHub project link.