Theme header hierarchy leaking into markdown #14578
Description
This issue came out of luizdepra/hugo-coder#989 (comment).
Problem: Most themes use a <h1> for the title of my markdown, but not all. This means that when I write my markdown, I need to know that my top header hierarchy should be ## and not #. This is a leaky abstraction.
Expectation: Is a markdown author, I would like to be able to simply write my markdown, using # as my top header hierarchy, without needing to know which theme I use. This has the added benefit that I can easily switch theme without having to modify my markdown files.
Proposed solution: As luizdepra/hugo-coder#989 (comment) states:
When I initially wrote created this issue, I was hoping that there would be one of the following two solutions here:
- Use something else than
<h1>for the theme's page title in the body. My frontend skills are a little rusty, but my local ChatGPT tells me that using<h1>for the<head><title>is the best-practise.- Map # to
<h2>for this theme. As far as I know, this isn't possible.
My proposal is that a theme can define which <hX>, # should map to. This would allow a theme to define that. One solution how that could be done, would be to have a magic frontmatter tag, say headerLevel: 2, which themes could define in their archetypes. This would also allow for easy migration of old markdown files, by setting headerLevel: 2 in frontmatter and doing a s/^##/#.