Hugo URL Aliases

When I built and posted some content on my site today using Hugo v0.53, I found that I had unintentionally broken some permanent links I was proud of. Thankfully, Hugo has a built-in feature - aliases - to address this issue.

Before I started the day, I was thinking about writing new posts. I was not planning to spend a good chunk of an hour trying to diagnose why some links I had posted to Twitter in 2018 were suddenly broken.

Example Symptoms

Below were the set of URLs that I had been using for a while:

1
2
3
4
5

https://sheppard.in/2018/kubernetes-by-component---part-1/
https://sheppard.in/2018/kubernetes-by-component---part-2/
https://sheppard.in/2018/kubernetes-by-component---part-3/
https://sheppard.in/2018/kubernetes-by-component---part-4/
https://sheppard.in/2018/kubernetes-by-component---part-5/

And this is what they were now after I rebuilt and posted to my site after updating to the current verison of Hugo (v0.53).

1
2
3
4
5

https://sheppard.in/2018/kubernetes-by-component-part-1/
https://sheppard.in/2018/kubernetes-by-component-part-2/
https://sheppard.in/2018/kubernetes-by-component-part-3/
https://sheppard.in/2018/kubernetes-by-component-part-4/
https://sheppard.in/2018/kubernetes-by-component-part-5/

At first, I thought that I had simply posted the links incorrectly in one of the posts and somehow failed to test them. Later, I realized I wouldn’t have done that most likely and I checked what Twitter had. Sure enough, the permalinks were now different.

For some reason that I have yet to track down, the - in the title of those posts was no longer being rendered in the URL as ---. It looks cleaner, sure, but it breaks the concept of the permalink it was supposed to be - never changing!

So Now What

After searching a bit and failing to find when this change had occurred and why, I looked into how Hugo lets you manage URLs again.

Right under the block about Permalinks was a block about Aliases.

By adding somthing like the following to the front matter of each impacted post, I would be able to redirect the old URL to the new one.

1
2

aliases:
    - /2018/kubernetes-by-component---part-1/

I don’t like that I needed to do this and I’m not entirely confident that other URLs I have used haven’t also changed. But for now, I’ve learned how to take advantage of a new-to-me Hugo feature and solved the problem enough to move on.