Customizing the URL for Posts

By default, your blog contents show up under posts/. For example, your first blog post is available at http://localhost:1313/posts/first-post. Many blogs use the year/month/title format for their blog post URLs. This meaningful URL shows anyone looking at the URL how old the post might be, but it also shows that the content is organized by date. In sites with content organized like this, a visitor could see content for the rest of the month, or for the whole year, by specifying the year or month.

A permalink is a permanent link to a specific page, often used when sharing a page with others through social media, newsletters, or even search results. You can use front matter on a post to control the permalink for a post by using the url field, but that’s really only meant to handle situations where you’re migrating content or need to do some one-off customization. Hugo lets you define how you’d like to structure your links in its configuration file.

In config.toml, add a new Permalinks section and define a new rule that makes posts available under /posts/year/month/slug:

This gives you URLs like /posts/2020/01/first_post. The slug is the end part of the URL that identifies the page’s content. It’s generated from the page title by default, but you can define your own slug by adding a slug field to your page’s front matter section.

If you visit /posts/2020, you might expect to find a list of all posts for that year. Unfortunately, Hugo doesn’t support generating these pages currently, at least not without a little extra work.

However, one of Hugo’s maintainers offered a practical workaround.^[24] By using Hugo’s taxonomy feature and a little clever use of front matter, you can generate archive pages of posts for years and months. You’re going to add “year” and “month” as new taxonomies, and “tag” your posts with a year and month. Hugo can then build the year and month pages for you just like it builds pages for categories and tags. You’ll use this approach with some minor tweaks to build out your pages.

First, add year and month fields to your content’s front matter. For the year, use the four digit year. For the month, use the four digit year, a forward slash, and the two digit month. For example, for a post written in January of 2020, you’d add these fields:

Open content/posts/first-post.md and add the year and month fields:

Adding these fields every time you create new content on your blog is going to get old pretty quickly, and it feels redundant. You can generate these in your posts.md archetype. It’s already getting the date, so create these fields in the archetype and extract the month and year:

The dateFormat function uses Hugo’s date formatting strings and applies them to the given date. Now when you generate new pages for your site, the month and year front matter will be created. Create a new post for your site to verify that these front matter changes work:

Open content/posts/second-post.md to verify that the month and year is set:

Next, open your site’s configuration file and define permalinks for the year and month pages. Add this code:

Finally, to generate the archive lists, define the year and month data as new taxonomies. To do this, add a taxonomies section to the configuration file, like this:

When you define a taxonomies section in your configuration, it replaces the defaults. To keep support for tags and categories, you have to explicitly define them now that you’ve customized things.

Save the configuration file. Your default list layout will handle the actual display of the posts, so when you visit /posts/<year> or /posts/<year>/<month>, the posts for that section will show.

They don’t look very good, though, so let’s fix that.