How to customise categories and tags URLs in Hugo

Generate pages for categories or tags on any URLs with Hugo

394 words · 2 min read

Update: Here is a new advanced hack for customising categories URLs

Hugo is a great static site generator. Fast page build time and built-in live reload make Hugo a joy to use. But it isn’t without its limitation.

One of the limitations I touched upon is the lack of completely customisable taxonomies URLs. By default, categories are located in /categories/something, and tags are located in /tags/something. If you want to change the word “categories” or “tags” in the URLs into some other words, there is a simple solution, as I explained on Github:

Change the taxonomies part of the configuration file into something like this:

tag: "hello" 

and in the front matter of your page, instead of using “tags”, you use “hello”:

- tag1
- tag2 

The path to the tag listing will become http://yoursite/hello/tag1

But if you want to remove the word “categories” altogether, I have figured out a way to do it, which is quite similar to how you create category pages in Jekyll.

Let’s take the category “short stories” as an example. First, create inside the content folder with the following front matter:

layout: cat-list
title: Short Stories
description: My latest short stories
pagecat: short-stories
url: /short-stories/

Next, in the layouts/_default folder, create cat-list.html with the following:

{{ $pagecat := .Params.pagecat }}
{{ range $key, $taxonomy := .Site.Taxonomies.categories }}
  {{ if eq $key $pagecat }}
    {{ range $taxonomy.Pages }}
    <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
    {{ end }}
  {{ end }}
{{ end }}

This reads the pagecat parameter from the front matter and matches with posts categories. Now, you can run hugo server and see a list of all short stories in localhost:1313/short-stories/. If you need a page for another category, simply create another markdown file with the appropriate front matter.


This workaround isn’t perfect. For a start, categories pages created using this method does not have pagination, which means visitors for a category page with a large number of posts will have a long page to scroll through.

Also, having these pages on custom URLs will not stop Hugo from generating taxonomies pages, which means /categories/short-stories/ will still be generated. One workaround, if you publish your site on Github, is to put the categories directory into .gitignore.

Admittedly, this isn’t very pretty, but it does the job. If you have figured out a cleverer way to do this, please let me know in the comment below.

 Tech    13 May, 2016
 Hugo    Web Development    Static Site  
Copyright © Peter Y. Chuang 2019

Peter Y. Chuang


Peter Y. Chuang is a novelist, short story writer, and a music critic. When he’s not writing or reading, he’s probably listening to classical music or tinkering with his computers. He uses Linux (current distro of choice: Arch Linux). Read more about his Linux stuff.

You may also like...