I completely agree with the confusion stated by other users. I was googling the issue when I found this issue report.
Coming from other template-overriding worlds (such as the Jinga engine in Sphinx), it didn’t even occur to me that a template overriding mechanism such as this would work differently than per-file. Implicitly overriding the whole theme folder (in this case, the archetypes folder) just because one single bit of its contents has been overridden seems not only counter-intuitive, but also opposite to the principle of keeping the changes at a minimum.
I think the Sphinx way of doing things is very sensible, so I’d like to contribute by quoting the most relevant bits of their Templating page:
Sphinx will look for templates in the folders of
templates_pathfirst, and if it can’t find the template it’s looking for there, it falls back to the selected theme’s templates.For example, to add a new link to the template area containing related links all you have to do is to add a new template called
layout.htmlwith the following contents: […]
Note: templates_path in this context would be equivalent to the archetypes folder in Hugo.
The example shown there would then override the contents of the theme’s layout.html file, but exclusively that one. It would seem nonsensical that just one single change in one single file would make the engine to override all other files from the theme! But precisely that is what Hugo does with the archetypes.