The update process consists of:
- Updating Academic
- Migrating your content front matter and configuration by applying any relevant breaking changes
Before updating Academic, it is strongly recommended to make a full backup of your website folder (including
Then, record your current version, so that after you update Academic, 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. Note that if you installed 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.
Academic Kickstart comes with an update script to check for available updates - just remember to temporarily comment out the last line so that you can view the list of available updates first without actually performing the update.
Please follow the method below which corresponds to how you originally installed Academic:
If you installed
By default, Academic is installed as a Git sub-module which can be updated by running the following command:
git submodule update --remote --merge
If you installed by Git cloning
Before updating for the first time, the remote origin repository should be renamed to upstream:
$ cd themes/academic $ git remote rename origin upstream
To list available updates:
$ cd themes/academic $ git fetch upstream $ git log --pretty=oneline --abbrev-commit --decorate HEAD..upstream/master
Then, update by running:
$ git pull upstream
If you installed from a ZIP
Uninstall your current version of Academic by deleting the contents of
themes/academic/. Download and extract the latest version of Academic to your
When you update Academic 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 your site was previously on v2.4.0, then apply the breaking changes for the consecutive releases since v2.4.0, i.e. [v3.0.0] and [v3.1.0] .
To help migrate content to be compatible with new versions of Academic, there are some tools available in the Academic Scripts repository.
Check out the [release notes] for the consecutive version that you are updating to, paying attention to the breaking changes. 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 the latest example site to check if any settings changed in
config.toml or the
+++ front matter of content files.
If you have modified files in
themes/academic, git will attempt to auto-merge changes. If conflicts are reported, you will need to manually edit the files with conflicts and add them back (
git add <filename>).
Also, if you overrided any Academic files (by using Hugo’s inheritance principle), then these may cause conflicts after updating. Consider removing them or 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).