Organize your Hugo content folder by year, without affecting any URLs

I made it two years into self-hosting this blog without a post about self-hosting a blog, but it’s finally time.

So you’re hosting a Hugo site, and your posts are in /content/blog or /content/posts or whatever, all lumped together. Your theme probably has a [Params] section in config.toml with a mainSections parameter that lists this folder. If you’re the only author, likely you just have everything dumped in a single section here; maybe you instead have things grouped by author, or maybe something else.

Now say you want to have /content/2021, /content/2022, etc, but NOT have the existence of these subfolders affect the URLs. How can we do this?

Turns out, it’s pretty easy, but when I was trying to set it up for my fantasy novel review blog I couldn’t find any documentation on it, so now I’m documenting it here!

Make the blog recognize all of the subfolders

This is done via the mainSections parameter in [Params] in your config.toml. It’s a standard parameter, so most (all?) themes should recognize it. Once this is set, all of the posts from all of the years will populate in your main page and list of all posts.

1
2


[Params]
  mainSections = ["2021", "2022"]

Stop the subfolders from affecting the URL

For this part, you use the [permalinks] section in your config.toml (this is a separate top-level section, not underneath [Params]). You probably will have to add this section yourself; it won’t be part of the boilerplate that your theme gave you.

1
2
3


[permalinks]
  '/2021' = '/:slugorfilename'
  '/2022' = '/:slugorfilename'

And so forth.

Hugo has some documentation about this section, but bear in mind that their examples all demonstrate how to do the opposite of what we want, namely that they want to add dates to the URL rather than remove a folder path (which happens to be the year) from the URL.

De-pluralize the year in breadcrumbs

There’s one final step: Our breadcrumbs will now be Home > Year > Post name. But Hugo by default attempts to pluralize the name of the category in the breadcrumbs, so it will say, for example “2021s” instead of “2021.” This is pretty bad, but fortunately there’s an easy workaround.

Create a file called _index.md in each of your year folders (/content/2021 etc) with the following contents:

1
2
3


---
title: 2021
---

That’s it. We give it the front matter saying what we want the title to be, and no content, and it’ll apply that title and otherwise display the default category page when we click there in breadcrumbs.

If you want a different title, like “Posts from 2021” or something, of course you could also do that.

But…are you sure you want to do this?

You may want to consider for a bit before committing to this folder structure.

Advantages to organizing by year

You have fewer things in each folder

That’s…….basically the only reason to do this.

Disadvantages to organizing by year

If you forget what year you published something in, it’s significantly harder to find that post
Posts that you leave as drafts for prolonged periods of time (spanning a new year) will have to be moved to a new folder before publication

Changes that may be advantages or disadvantages

You may prefer the breadcrumbs change mentioned above; you may not. That’s a matter of personal opinion.

Verdict

Unless you really want the breadcrumbs change, I would make this change only if you have an extremely high post volume. If you post less often once a week, it’s probably not worth it to organize your folder structure this way. You can always change your mind in a couple years - the change can be scripted by looking at the date: line in each file, and even if you don’t want to script it, manually sorting under 100 things doesn’t take THAT long, all things considered - and you won’t get up to 100 things for at least 4 years with a post volume of once every-other week. Even if you post a bit more, or delay a bit longer, manually organizing 200 things isn’t that bad. You’ll probably lose more time looking for posts that you forgot the year in which you posted them than you’d spend (potentially) reorganizing once in a couple years.

But for an extremely high post volume, this change is pretty nice (which is why I’m doing it on my fantasy review blog). Especially if you compose posts in something like VSCode using an SSH plugin with a file explorer panel, having a huge list of files in your current folder can be super annoying, and this system gets around that issue conveniently.