Update Academic theme to (renamed) Wowchemy

Updating Hugo themes is probably easy for most people, but I’ve managed to mess it up more than I’d like to admit. Here are the notes I took for this last update.

If you do not care to read (or about) all the words and explanations, feel free to skip to the SHORT VERSION

BACKGROUND

Let’s be honest, I don’t dedicate enough time to this blog and website. But I realize that there are tasks which need completing in order to keep it going. Updating the theme to capture the latest changes is one of those things and it is something I’ve messed up more times than I’ve gotten it right. I’ve attempted to use subtrees and submodules and always manage to muck it up (I admit that this might be due to my ignorance when it comes to git).

So I obviously dread this task because I am sure to create a headache for myself. Today, when I went to torture myself with this update, I learned that the Academic theme I have been using lately has been entirely changed and rebranded to Wowchemy.

In addition to what I am sure are significant and awesome changes, it now utilizes “modules.” I don’t claim to understand this, nor what the difference means, but I was pleasantly surprised that updating it was very straightforward and that the few changes I’ve made (such as updating the colors and creating a table of contents) still worked. I have not done thorough testing or investigation, but my initial impression is that everything works.

CHALLENGE

I’m delighted to report that this did not pose much of a challenge this time, I simply removed the submodule and pointed the “module” to use wowchemy. I’m not sure I’m using those terms correctly, but that’s how UNchallenging it was…I didn’t even bother to learn the new methodology.

SOLUTION

The solution was very simply to follow the Wowchemy documentation.

I admit that I am somewhat concerned that said documentation mentions migrating content and lots of other changes that I have not accounted for. I fully suspect this will break something in the future.

UPDATE [2021-01-30]

I’m happy to report that in addition to updating to the latest version of the new theme back in November, I updated it again to pull in the latest changes just the other day (don’t judge, I realize I haven’t done anything on the site in forever, but this updating was easy so maybe I’ll dread it less now).

This is all I had to do:

# from the root of my site repository
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod clean
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod get -u
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod tidy

NEXT STEPS

• I need to spend some time ensuring everything works as I think it does
• I need to read up on the changes to see what additional steps I might need to take to future-proof this

SIDE NOTES

• before I knew Academic had been rebranded, I attempted to use a new branch for the changes I was about to make. This is because I fully anticipated breaking things. Turns out that wasn’t necessary, but that required me to figure out how to merge my changes back into my main branch once I figured things out. This is git 101, but since I don’t use it regularly, it challenged me and so I thought I’d not it here
• I do not know what this modular approach means for when I want to keep up with changes to Wowchemy…I used to have to try to pull down new changes to the theme to my own repository, but now I’m not sure…

WHAT I LEARNED

• I think I like that Hugo transformed to use a plugin-like Module system as the core building blocks in Hugo and that Wowchemy (formerly Academic ecosystem) adapted to use them!

REFERENCE

• Wowchemy: Uniting the Hugo Academic Ecosystem, Empowering Creators - blog post
• Introducing Wowchemy Version 5.0 (WIP)
• Migrate Content - I straight-up didn’t do this
• Convert an old Academic Kickstarter site
• Hugo Modules
• Supported Hugo Versions

SHORT VERSION

To avoid tl;dr enjoy this instead:

# from the root of my site repository
$ git submodule deinit themes/hugo-theme-academic
$ git rm themes -r
$ rmdir themes
$ sed -i 's/^theme = /#theme = /' config/_default/config.toml
$ cat <<EOF>> config/_default/config.toml

# using modules: https://wowchemy.com/docs/install-locally/#convert-an-old-academic-kickstarter-site
[module]
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/wowchemy"
  [[module.imports]]
    path = "github.com/wowchemy/wowchemy-hugo-modules/netlify-cms-academic"
EOF
## the documentation doesn't specify where go.mod and go.sum reside, but I put
## them in the root of my site repository and it seems to work:
$ wget https://raw.githubusercontent.com/wowchemy/starter-academic/master/go.mod
$ wget https://raw.githubusercontent.com/wowchemy/starter-academic/master/go.sum

################################################################################
## UPDATE [2021-01-30] - how to update the wowchemy modules to get latest
# from the root of my site repository
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod clean
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod get -u
podman run --rm -it -v $(pwd):/src:Z -p 1313:1313 klakegg/hugo:0.78.2-ext mod tidy