Does Hugo support categories in the permalink?


I am trying to port over a Octopress blog over to Hugo, and was wondering if a post permalink like:


would work! is not very encouraging!


It depends what you mean by “categories”. In Hugo terminology that’s probably section… but the default behavior of Hugo is already /:section/:title/ so that’s pretty much what you want. If you turn on ugly urls it will do it exactly as you’ve specified here.


So in my Octopress blog, I had front matter like so:

layout: post
title: "Chrome DevTools Profiling Demystified"
date: 2013-05-12 09:30
comments: true
category: engineering

And that would end up with a url like:

So the :categories would get picked up from the front matter and used in the URL.



Hugo just does things differently. You can specify the section in the front matter and it would work the exact same way. No permalinks needed. You also don’t need to specify the layout in hugo (unless it’s different for that post). It will guess it from the section.


Sorry to bump an old thread, but I’m currently trying to set section in the front matter, and it doesn’t seem to be acting as I was expecting. I’m currently on the 0.15 release.

There seems to be a bit of contradictory documentation on setting sections in front matter; at it says “section is determined by its location on disk and can not be specified in the front matter”, and at it says “By default everything created within a section will use the content type
that matches the section name. Section defined in the front matter have the same impact.”

Here’s my specific situation: I have a piece of content and in the front matter I’m setting the section to “travel”. I want the destination URL to be /travel/piece-of-writing.html. If I put the file in content/post (where I’d like it to be) it outputs to /post/piece-of-writing.html, and if I put it in content without a section dir, it outputs to /piece-of-writing.html. I’ve tried setting permalinks in the config and leaving it out (since I’m using the default permalink arrangement).


First, the docs at your first link are wrong. The second link is correct.

Second, there’s two concepts at play here: output location and template selection.

The location of the file relative to the content folder determines its output location on the disk. You can see that behavior based on what you said in your last paragraph. You can override this behavior by setting the url field in the front matter.

The section or type is mainly used (at least the way I use it) for template selection. You can override the default section/type by setting the section or type field in the front matter.

UPDATE: My statement above is incorrect. You can only override the type, not the section.


I appreciate the help @mooreason! It seemed to me that in Steve’s post above he’s specifically saying that setting section in the front matter would reflect in the destination URL as OP was asking about. (“You can specify the section in the front matter and it would work the exact same way. No permalinks needed.”)

I was hoping I was running into a bug, or I was doing something wrong, but if that’s not the case I’m a bit bummed. I can make a pull request to correct the docs at, and if indeed setting section in front matter will never reflect in destination URLs, I’d think that should be documented somewhere too and if anyone wants to point out where, I’d be happy to make a pull request for that as well.


Not sure what I’m doing wrong but I have:

  doc: "docs"
  doc: /docs/:section/:slug

To display /docs/PRODUCT/TOPIC but it seems to not work, is it not supported for taxonomies?


Permalinks is a global setting, and it wouldn’t make sense/or be possible to include taxonomies in it.


Hey @tjholowaychuk, is your source organization for content the same as what we discussed before?

If so, remember that taxonomies work independent of section. So, in order to get all the .md files in your content/docs to be part of a specific taxonomy, you’d have to declare this specifically in the front matter of each content file; e.g.—

docs: [product, topic]

Both product and terms will show up as terms in a taxonomy terms list (i.e., as two items in

This specific content file will show up as part of a taxonomy list at and This is why the permalink isn’t working, since taxonomies are largely just a matter of default behavior, so there technically is no “section” in this case.

Does that help?


It seems really close to what I wanted, I have docs: ["Apex Ping"] in my ./content/doc/apex-ping/*.md files, and I just tried renaming that dir to “docs” but it 404s on http://localhost:3000/docs/apex-ping/alerts/ (previous http://localhost:3000/doc/apex-ping/alerts/ worked).

Thanks again!


Really? I’ve been doing this all wrong then…and definitely need some clarity on this for the docs. I’ve made multiple edits so that it consistently says that users cannot define section in front matter but can define type…with the idea that Hugo’s assumes they are one in the same if not otherwise specified on a per-content-file-front-matter basis.


@rdwatters, you’re correct. My previous statement is wrong. You can only override the type, not the section.


Hey !

You can only override the type, not the section
Is this assertion still up to date ?

As of today I have a flat directory structure like :

content /

What I need is to be able to set the section to be used within each posts’s frontmatter like:
permalink: /post/:title
permalink: /:title

which would result the same as physically moving around my posts in a /posts/ directory (which I would prefer no doing for obvious reasons: I don’t want to manage some content 5 levels deep !!! Who on earth would do that ?

So, I don’t really care about how you would call such parameter : permalink / section / url / whatever, but is this possible to not follow the directory pattern ?

Thanks !


Have you tried just putting url in a post’s front matter? You can configure entire sections at once in your site config as well…