Fix heading structure

[jtiala]

Blog posts are generated from markdown. It's pretty natural to structure the headings starting from h1 (# heading) in markdown, but this results in bad heading structure in the resulting web page. At the moment we have pages that look like this:

<h1>Blog post title from markdown frontmatter</h1>
<h1># First level heading from markdown</h1>
<p>...</p>
<h2>## Second level heading from markdown</h2>
<p>...</p>
<h1># First level heading from markdown</h1>
<p>...</p>

Correct structure would be

<h1>Blog post title from markdown frontmatter</h1>
<h2># First level heading from markdown</h2>
<p>...</p>
<h3>## Second level heading from markdown</h3>
<p>...</p>
<h2># First level heading from markdown</h2>
<p>...</p>

We should limit the headings generated from markdown to be no higher level than h2. Some posts might start from h2 already, so we cant just do heading + 1.

[esuomi]

Correct for this particular page, yes, but not from Markdown evaluation point of view. This is tricky since technically both are correct depending on approach.

To make this more confusing, a third option would be including semantic wrapper, eg.

<h1>Blog post title from markdown frontmatter</h1>
<article class="blogpost">
<h1># First level heading from markdown</h1>
<p>...</p>
<h2>## Second level heading from markdown</h2>
<p>...</p>
<h1># First level heading from markdown</h1>
<p>...</p>
</article>

with some rem adjusting CSS

.blogpost > h1 h2 h3 h4 h5 h6 {
    font-size: 0.85rem; // or whatever the scaling should be
}

but this of course would introduce two new problems:

1. One would have to make sure all headings on the page are scaled correctly and in such way that the scale matches between these "blogpost article headers starting from 1" compared to "all other headers starting from 2"
2. UX wise for screen readers and such this would probably make even less sense.

[jtiala]

I havent looked into this at all, but some markdown->html libraries let you say what is the top level heading it generates.

A11y-wise only 1 h1 per page seems to be the only viable solution. AFAIK the spec supports h1's for different sections, but support for those hasn't been implemented in any browsers. Check out this blog post about the issue.

[jtiala]

Also, semantically the first <h1> in your example should be inside the <article>, as it's the articles title.