Learn how to update the Wowchemy website components that your site uses.
TLDR
- Head over to your website project in Github, click the
go.mod
file, and click the pencil button to edit it - Update the
require
statement to the following to get the latest version:- Otherwise, to get a specific version of a module, replace
main
with a commit or tagged version that’s associated with the module.
For example, thewowchemy
module has amodules/wowchemy/v5.6.0
release which we can update to by replacingmain
withv5.6.0
in the relevant line below.
Click the green Commit Changes button to save your changes.module my-website go 1.15 require ( github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify-cms main github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify main github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-reveal main github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy/v5 main )
- Otherwise, to get a specific version of a module, replace
- Update the module paths in
config/_default/config.yaml
to the following if they are not already:module: imports: - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify-cms - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-reveal - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy/v5
- Update
HUGO_VERSION
innetlify.toml
to a compatible version from the Release Notes- Or, if you are building on your computer, update your local Hugo Extended to the compatible version
- Consecutively apply any breaking changes from the relevant Release Notes (older, pre-v5.3 notes are on the Blog)
- Check that the latest Netlify deployment of your site is successful (otherwise click the failed build to view the issue)
TIP: If you are updating from an ancient version, you may find it easier to create a fresh site and migrate your content/
folder across.
Join the community to learn when we release improvements:
- Star (and Watch) Wowchemy on Github
- Join the Announcements channel on Discord
- Follow @wowchemy and @GeorgeCushen on Twitter
- Subscribe to the blog RSS feed
Full Process
The update process consists of:
- Preparation
- Updating Wowchemy
- Migrating your content front matter and configuration by applying any relevant breaking changes
Preparation
Before updating Wowchemy, it is strongly recommended to make a full backup of your website folder.
Then, record your current version, so that after you update Wowchemy, you can apply any relevant breaking changes to the TOML/YAML site configuration and front matter in your content/
folder.
To find your current version, look in themes/academic/data/academic.toml
if it exists. Otherwise, you can get the version from go.mod
where it’ll either be an exact version like v5.0.0
or it’ll be a 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 master 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 Wowchemy
Prerequisites
Install a compatible version of Hugo Extended and its dependencies.
If your site does not have a go.mod
file, follow the Migrate Content guide below and then update your theme to version 5 to convert your site to use Hugo’s Module system. From Version 5 onward, you can update using the command in the Update section below.
Update
Hugo uses the go.mod
file to control which version of Wowchemy a site uses.
Open a Terminal (Command Prompt) and navigate to your site’s folder using the cd
command.
Update to get the very latest developments:
hugo mod get -u ./...
Alternatively, update to the latest official release:
hugo mod get -u
Migrate your content front matter and configuration if necessary by applying any relevant breaking changes.
Migrate Content
When you update Wowchemy 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 TOML/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 Wowchemy, there are some scripts available in the Hugo Scripts 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 TOML/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 Wowchemy/Academic 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.