Hugo doesn't use theme archetypes

Sigh, another confused user here. I am trying to make my own theme and was totally confused as to why my theme archetypes were not overriding the non-theme “” archetype.

I expect in 6 months when I do another install, and have forgotten, that I will have to go back through this confusion again because the logic seems all backwards.

Simply, if I am using a theme, the archetypes in the theme should take precedence, otherwise why bother with the theme archetypes?

How do I access my own ones anyway? It is far from obvious to me :frowning:

Using the logic on the doc page (shown below), I cannot even see how my theme’s archetypes could ever be accessed without first deleting “archetypes/”. This surely means that a fresh hugo site with a fresh theme will have theme archetypes can never be accessed unless the users first deletes “archetypes/”.

  1. archetypes/
  2. archetypes/
  3. themes/my-theme/
  4. themes/my-theme/
1 Like

I came across the same issue. Very confusing why my theme archetypes were not being applied unless I deleted the {site}/archetypes/

Reading up the thread I assume it depends on the how important themes are to Hugo moving forward

  • Content is my domain, i.e. the project. It contains dispositions etc. related to my topic. This is not a theme’s domain.
  • Theme is in most parts look-and-feel/UI. Something that could be switched out for something prettier if needed.
  • There are overlaps to the above, but any improvements to the current archetype lookup will have to take the above into account. I would be really surprised if a theme started to provide content overrides.

So, I see that there are different views on the above. I also see that the current model is not perfect. But this is an open source project. Create a proposal with a design and follow up with an implementation. I have spent a fair amount of time on the archetype system (we had a release not so long ago about it). To redesign this would probably be two days of work for me, including test and documentation. That is not currently a priority for me. But if someone else has that kind of time to contribute to this, go ahead.

I’m building a marketing website with Hugo + a custom theme and I’m hitting an archetype conundrum - I don’t think it’s a bug so much as a conceptual issue relating to Hugo’s paradigm of content, structure and design.

Currently, Hugo puts content and structure within the domain of a project and the visual presentation (themes) of that content as a logically separate entity. In the case of my current website project and many other custom website projects I’ve built (not withstanding conventional blogs), the visual design is intrinsically linked to the content model of the site.

I think my current approach will be to remove archetypes from my project folder (including default), only keep archetypes in my custom theme and so only get my custom theme ‘approved’ content structure.

Perhaps there doesn’t need to be any technical solution to this but maybe some documentation that addresses the use case of custom websites where the content structure and visual design are interdependent as opposed to a conventional ‘blog’ website where a theme is more or less reskinning an established content structure that matches the ‘default’ behavior of the archetypes that ship with Hugo.

I had the same issues. I think it was caused by mixing yaml and toml in happens in the Universal Theme.

Nope it wasn’t. Still having issues. Anybody solved this in the meantime?
My hugo is hugo v0.101.0+extended darwin/amd64 BuildDate=unknown on a macbook.
“Error: failed to resolve “blog” to a archetype template” is the error I get.

What command triggers this?
What is the structure of your archetypes directory (if any)?
What is the structure of your theme’s archetypes directory (if any)?

hugo new blog/techniek-electrolysers
Used theme is Universal
Structure of archetypes directory:


structure of theme’s archetype directory


Error: failed to resolve "blog/techniek-electrolysers" to a archetype template


hugo new blog/

Hugo supports .html as well, so you need to tell it what type of file you are creating.

1 Like