Why does markup.tableOfContents.startLevel default to 2?

The Table of Contents settings have these (TOML) default values:

    endLevel = 3
    ordered = false
    startLevel = 2

But why startLevel = 2?

I realize I can just set startLevel = 1 in config.toml, but before I do, I’d like to know: Why this isn’t 1 the default value? Put another way, why are Heading1s like

# Heading

ignored in .TableOfContents by default?

I can’t find anything in the CommonMark spec that suggests not to use Heading1 in my posts. It worries me a little that this default will teach people to start their heading levels with Heading2, but perhaps I’m missing something.

I believe that for SEO reasons you would want your article title to be the only h1 on the page. I remember long time ago the behavior you are expecting was the default one and nobody was happy about it.

That is it. There is a debate whether Google etc. care about this, but I think it’s at least feels natural to have the page sections as a tree with one root (h1), which is impossible if you start out with h1 in the markdown.

Ok, thanks guys. So there is a reason.

And I see that at least with the Ananke theme, the page title (from the page front-matter), is shown prominently at the top of the post, serving that purpose. And a <h1>is used for that.


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