Custom Permalinks Variables


I’m migrating my site to Hugo and I’m struggling to find a way to have the structure I want.

Ideally I would like the Docs section to be in the main page, but by doing so, the docs content are treated as sections, which is not what I want. So I think it would work well enough by handling urls from the permalink point of view. However I don’t want the section to be present in the URL. The Permalinks variables seem hardcoded in the source code “/resources/page/permalinks.go#L66”. So it doesn’t seem there is a way to customise them. Only :section and :sections would help me, but both have the “/docs” on it.

My site URL looks like:

However I’d like to have:”.

The only way I can find is by using page variables. Using the “url” page variable or playing with the slug and the permalink configuration. Both solution require to hardcode the url or alike for every page of the site, which is not maintainable as the site is big enough.

Do you have any insight on how to achieve this?

Thank you

I couldn’t add the proper link on the description as 2 urls are restricted for new users. The source code reference I meant in the original post is:

In Hugo, the base of your URL structure starts at the content root(s), and you can put that wherever you want.

So if you have content/docs you can set it to be just that, and you will, in my head, get what you want.

Also see

Thank you for your answer @bep.

I’ve been trying your suggestions without success. I can see what you mean about putting the content in the root by either moving the page sections or using the mounted modules. However, my issue stands the same.
The first level of pages and directories are treated as sections, which breaks the documentation. I don’t know if there is a way to tell hugo to don’t treat them as sections, but part of the behaviour applied for docs.

To exemplify:
the original site would have in the following example 2 sections “docs” and “blog”.


When I navigate through the site, blog is treated as a section and docs as well. So if I go into the docs section. I can navigate through my documentations, architecture or cookbook. If I change sections and go to blog, I would see the other part of the site.

In the aim I have, when I make my docs section the root because it is the only thing I want in the website, I would have:


In this situation, whether with modules or moving content around, the site creates 2 sections. “concepts” and “how-to”, and the visualisation and navigation is the same as described in the previous example. A behaviour I want to avoid. I just want the root of the site to behave as if it was the docs section, without having the “/docs” in the URL.

I’m not knowledged about Hugo internals, so please let me know if I’m missing something obvious.