This Series is Out of Order

To Err is Human: Out of Order

Well it happened, I made a mistake on the internet. I’ve been working diligently on the “Build a Website” series, and what I expected would happen in my creation of a series of articles has happened. I wrote some of them out of order. This is a minor headache so I’ll share what I found.

One feature I’m proud of is the custom taxonomies I’ve made for this site, including the tags, and series listings. One of the most essential properties of a series of articles is the fact that they happen sequentially. This isn’t really a problem for Hugo: just add the posts to the series and you’re done! Well sure, you’re done if the order of the series is in the order that you wrote them. But I did not do this.

While writing “Getting Started With Hugo Partials” I realized that some of the code I had been talking about was really better off coming before I started talking about how to get style into the page, because I’m already talking about partials in the “With Style” article without saying it. Plus, the original repo has some minor stylistic differences that are annoying to reconcile as I’m trying to write the whole thing. This might be a simple built-in reorder if I wasn’t using Hugo.

Ordering Outside the Box

Hugo is designed in a way which implies that the only way that you’d ever want to order your taxonomy’s articles is either by some variation of date, length, alphabetical incidence, or weight, at least most of the time. I’ve found while working at this level the only ordering methods your can really get access to are date and weight. The full docs are here, but the problem I basically hit was that I wanted a property that only mattered within the series. I didn’t want to change history to get my series in order correctly.

Now, you might think, “Jon just use the weight system it fixes your problem,” and yeah … about that. If you don’t use ‘weight’ for all of your articles you’ll probably find that you’ve just messed up, good job. Wait, how? The default precedence for how to sort things is this:

Weight > Date > LinkTitle > FilePath

If you have other lists that don’t explicitly order by date or, better yet, if you have lists that do use weight, now you’re confusing around 3 different things. I don’t know if I actually want to use weight for my site, but I do know that what order a series in a list happens to appear in shouldn’t make it more important than articles I forgot about labeling. Unless I want to mark all of my articles as “weight: 100” or something it’s not what I want. But then, what’s the point? Aren’t we mixing up the semantics of what we’re actually trying to do?

What I wanted is a custom property that can be ordered like date, weight, etc. without messing up the other properties like date, weight etc. It was a bit of a bear to figure out how to do it, but it’s pretty simple.

Custom Properties

If you want a custom property that tells your custom taxonomy where inside a term it should be sorted, without messing up the other default ordering methods then you’ve come to the right place! But what an odd question.

In your front matter for your series articles put something like this

---
title: "The Best Series Ever"
date: 2020-12-14
series: "Super Series"

order: 2

---

That Property order: 2 is pretty important now, so for every other object in that series, make sure you’ve got something. If you double up on numbers, then Hugo will default to the other methods of sorting, which is what we’re trying to avoid.

Now you have your custom property, but that doesn’t do anything if you don’t sort your pages using it. So do this on your series/taxonomy.html:

{{ range sort .Pages  "Params.order" "desc" }}

And bam you’re now sorting by that custom property, and it doesn’t mess up any other sorting!

The Takeaway

If you’re working with Hugo, like me, then you’ve got a lot of control over how your content is displayed, it’s just not always obvious how to do that. When I looked at the documentation for Hugo, I thought you might be able to work with a simple .Pages.ByOrder or something. To figure out that you could do a range sort I had to go searching on the forums, which pointed me to sorting on page parameters.

I found what I was looking for, thankfully. Maybe it’s a good thing that novice users can’t figure out the heretical knowledge that I know about sorting on custom parameters. There’s definitely more arcane info on the top-level documentation for Hugo. I’d guess that the reason is that this is more a Go thing, rather than Hugo. Unfortunately for me, this is one of my first forays into Go programming in general, and I think this will be the case for a lot of

The best thing I got out of all of this, is the Hugo community is pretty great. It’s got a lot of hackers and passionate users who like to share their info with others! Maybe that’s not surprising for a blogging app, but it’s refreshing nonetheless.