Makes enough sense, but I’m wondering about the role of the partials that Hugo ships with; i.e., _template/*. Are these overridden by files of the same name in partials? Mostly I’m wondering for the docs themes and templates sections. If a theme developer adds the internal template but the theme user wants to “override” the template to maintain compatibility with the upstream, what’s the best way to do this? I ask in light of recent realization that there are other internal templates that ship with Hugo that aren’t documented.
The problem is figuring out where this documentation should live within the content source. Right now, there are built-in Hugo shortcodes…so I assumed these are kind of like “built-in Hugo partials,” but I guess this could be accompanied with text explaining that they do not observe the lookup order. I would also like to add the undocumented templates. Thoughts, @bep?
We have some internal templates loaded via template _internal … something. Having them live on the side as something special is probably a mistake that someone should fix – so everything can be loaded via the same partial func.
I agree, but I’m talking more about how to group this in a way that makes sense for end users rather than separate “Analytics” and “Comments” pages. I’ll have to stew on this for a bit. Thanks!
does this have anything to do with the previous isset conversation?
No.
Are these overridden by files of the same name in partials?
Yes. If a theme author creates themes/<THEME>/layouts/partials/foo.html, you would override the theme partial with layouts/partials/foo.html.
If a theme developer adds the internal template but the theme user wants to “override” the template to maintain compatibility with the upstream, what’s the best way to do this?
There’s nothing particularly special about overriding the theme. It’s the same procedure. If a theme author wanted to override the Disqus template, they would create themes/<THEME>/layouts/disqus.html. A theme user would override the theme version by adding layouts/disqus.html.
I agree with your concern that the internal templates should be better documented, but there are no internal partial templates. This section title should get its own page.
Current internal templates can been seen here. The list:
To override an internal template, you (or a theme author) would create a template with the same name but without the leading _internal/ prefix. See Disqus example above.
Haven’t tested this idea, but if you wanted to ignore a theme’s version of an internal template, you could create layouts/disqus.html with content:
Huh. So all metadata, then GA, and then comments. I wouldn’t want these to get lost under “internal templates,” so I might group to make more discoverable but I have to stew on this.
I will try to test later, but if true, this means the current documentation is incorrect (i.e., in that it specifies creating a conditional loading template for Disqus in the partials and not layouts dir). Or maybe it’s correct but confusing.
The “lookup order” is a common point of confusion, so the more this can be clarified in the docs, the better…