SEO optimization: how to force `#` to generate h2, and so on?

For SEO optimization, it is said that only a single H1 heading should be present on the page, and most of the themes already default to using it for the post’s title.

Is there a way to configure markdown parser to treat a single hash (#) as a h2 heading, and so on? Obviously I can simply resort to using double ## headings, but I am afraid I’ll forget sometime down the line.


The content below the front matter should never contain a level 1 heading. If you’re afraid you’ll forget, add it to the archetype(s) content.

1 Like

This isn’t too obvious until you actually read into SEO optimization. And if the content below the front matter should never contain a level 1 heading, then why even make it possible? Wouldn’t it make sense to have Hugo automatically generate h2 headings by default, possibly exposing this as an option?

Because maybe you don’t want to have the H1 title in a template, but instead in content.

If you feel strongly about this I supposed you could create a heading render hook that adds 1, but then your rendered Markdown will not conform to either the CommonMark or GitHub Flavored Markdown specification.

I just realized that even if I do remember about limiting h1 usage myself, I have a comments section on my website where markdown is accepted as well. So any #s there will inevitably end up in making that page non-conformant to SEO rules.

I believe this is a bigger issue than it appears to be and a systemic solution to this would be worth looking into.

See my previous reply, but you’re on your own regarding whichever commenting system you’ve integrated.

This sounds like better addressed by a linter, not hugo (the “compiler”).

markdownlint has a rule that performs exactly what you need:

It detects whether there’s a title in the frontmatter. If so, it would report h1 in the body as an error. If there’s no title in the frontmatter, it detects whether the body contains no more than 1 h1.

This is brilliant and indeed makes more sense in this case. Thank you!

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.