Why <h1> should be one per page?

[debiru]

Hi, I have questions about the following.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements says:

Use only one <h1> per page or view. It should concisely describe the overall purpose of the content.

However, there is no explanation of how one would benefit from one, or what the problem would be with more than one. It is also described as a best practice, but no rationale for this is provided.

How on earth did it come to be said that only one <h1> is better than the other?

If anyone knows anything about this, I would appreciate an answer.

[schalkneethling]

@debiru Thank you for asking the question. I believe reading these will help explain the reasoning behind this:

• https://webaim.org/techniques/semanticstructure/#headings
• https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#one-h1

[debiru]

Thank you for your reply. But, my question has not been resolved.

Firstly, https://webaim.org/techniques/semanticstructure/#headings

Headings create an outline for the page, similar to a term paper outline or table of contents.

OK. Exactly.

The <h1> describes the page as a whole (and should be similar to the page <title>). A page should typically have only one <h1>.

Abruptly, it was argued that h1 is equivalent to title. Is there any fact that the meaning of h1 has been changed by WHATWG?

Secondly, https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#one-h1

Using multiple h1s was proposed with the introduction of the HTML Document Outline in HTML5.

It is a factual error. The use of h1 - h6 as headings, especially the use of multiple h1s as well as h2 and beyond, as in the outline of an article, has been common since the HTML 4 era.

There are three main types of markup involved in headings.

• (1) Use h1 - h6 elements without section element.
• (2) Use h1 - h6 elements with section element.
• (3) Use only h1 element with section element.

Concluding: Multiple h1s on sections to create a document outline is not supported by browsers and therefore outdated.

OK. This means that (3) is obsolete.

Use one h1, describing the content of the web page. Structuring the rest of the content with meaningful subheadings. This serves accessibility and SEO best.

Abruptly, it was argued that having only one h1 is advantageous for SEO.

Overall, no reason is given why h1 should be one per page.

If h1 should be one per page, it means that the usage of the element is asymmetric with h2 and beyond. Is there any mention in the HTML spec that h1 is such a special entity? If SEO is the main reason, then docs should says that a single h1 is better for SEO, even though it has nothing to do with the spec.

It seems to me that MDN is baselessly saying that there should be only one h1.

[schalkneethling]

Nothing in the spec prevents you from using multiple level one heading elements on a page. So, I would say this is definitely something that is considered a best practice and aids in SEO.

• https://html.spec.whatwg.org/multipage/sections.html#outline
• Suggest adding a warning about outline algorithm whatwg/html#83
• replace current outline algorithm with one based on heading levels whatwg/html#7829

@Rumyra, thoughts on this one?

[debiru]

mdn/content#18559
What is this update all about by this Pull-Req?

Are you mistaken about something? There should be no direct link between the abolishment of the outline algorithm and the pros and cons of using multiple h1s on the same page.

Do not use multiple <h1> elements on one page

This wording is problematic because it is misleading. There is nothing in the specification that restricts multiple occurrences of h1.

I request a correction to the English version.

[robinmetral]

What is this update all about by this Pull-Req?

As you can see in the diff, the recommendation to avoid multiple H1s was not introduced in the PR but existed in MDN before that (in the context of the outline algorithm). So essentially there was no "update" to speak of.

In any case, since I opened the PR, I'll try to help clarify things.

Is the phrasing on MDN misleading?

Yes, I agree that it is. The phrasing mixes up the spec and best practices. This was briefly acknowledged and discussed in a PR comment, but should definitely be clarified in the docs. See "Next steps" below.

However,

There should be no direct link between the abolishment of the outline algorithm and the pros and cons of using multiple h1s on the same page.

No. There is an obvious direct link. Using multiple h1s in a nested structure is not allowed anymore, since the removal of the outline algorithm from the HTML spec. It remains allowed only if the h1s are not nested. This should remain clear in the docs.

Examples

This isn't allowed (invalid HTML and harmful to assistive technology users):

<main>
  <h1>Page title</h1> <!-- h1#1 -->
  <section>
    <h1>Section title</h1> <!-- h1#2 -->
  </section>
</main>

This is still allowed:

<main>
  <h1>A first section</h1> <!-- h1#1 -->
  <!-- ... -->
  <h1>A second section</h1> <!-- h1#2 -->
</main>

Is having only one h1 per page a best practice?

I would argue that it is:

• your document must have a tile (<title>) that accurately describes its contents/purpose
• sighted users will likely not see the (full) title
  • e.g. the title may be truncated to fit a browser tab width; mobile browsers typically don't show the title unless looking at the list of opened tabs (where the titles are also truncated)
  • note: this is not an issue for screen reader users since the title is announced when a page first loads
• therefore you'll probably want to display the title on top of the page using an h1 (this is where the advice "the h1 should match the page title" comes from, I imagine)
• if your h1 matches your page title, all other headings should be nested hierarchically under the h1

Naturally there can be exceptions to this. Still I believe that this can be mentioned as a best practice on MDN (with the clear mention that this isn't a spec requirement).

For example, this is how it is phrased by TPGi (source):

[...] a top-heavy heading hierarchy is unusual but not incorrect. Users typically expect only a single <h1>, which is used to represent the main heading or title on the page. As long as the visual presentation of multiple <h1>s doesn’t imply a hierarchy (such as the first <h1> being styled visually to be larger or bolder than the second <h1>), then having more than one <h1>—while potentially confusing—does not represent a WCAG failure.

Next steps

I'll reiterate what I wrote in the PR:

Since the current version of the page is recommending against using multiple h1 elements, I haven't changed it.

Happy to work on a rephrasing if we'd like this to be clearer on the docs! (or to take suggestions on how to explain this)

You "request a correction to the English version". What is your suggestion? I'm sure that the MDN maintainers would be happy to continue the discussion in a PR. Do you want to open one? I would be happy to do it but am a bit busy these days.

Last but not least: I found some of your comments here (and on Twitter) aggressive and disrespectful. Please be constructive and avoid personal attacks. Refer to the Mozilla Community Participation Guidelines.

[debiru]

Thank you for the reply. I appreciate the detailed description.

From reading your description, it seems to me that you have the same understanding as I do. In other words, it seems to be a matter of different expressions.

Whether or not they are directly link

This is still allowed: (<h1> ... <h1>)

Yes, When I said it was "there should be no direct link", I was referring to this.

I meant to say that since this case is allowed in the spec, multiple h1s can be placed regardless of whether or not the outline algorithm is obsoleted.

Is having only one h1 per page a best practice?

I would argue that it is: ...

I think it makes so much sense.

Next steps

What I see as a problem is the statement "Do not use multiple <h1> elements on one page", which leads more and more (Japanese) people to misunderstand that multiple h1 descriptions are not allowed in the specification.

As you can see in the diff, the recommendation to avoid multiple H1s was not introduced in the PR but existed in MDN before that (in the context of the outline algorithm). So essentially there was no "update" to speak of.

As an addendum, I am not only concerned about this Pull-Req. As I started this thread, I am aware of the problem from the description in the previous version.

You "request a correction to the English version". What is your suggestion? I'm sure that the MDN maintainers would be happy to continue the discussion in a PR. Do you want to open one? I would be happy to do it but am a bit busy these days.

The specific request includes:

• I want to distinguish between spec talk and best practice talk.
• I would like to provide as much detail as possible as to the rationale as to why a single h1 is considered best practice.

This is to eliminate the misconception that one should not write more than one h1. On the other hand, I also understand the need to communicate best practices that one should not write more than one h1.

Last but not least: I found some of your comments here (and on Twitter) aggressive and disrespectful. Please be constructive and avoid personal attacks. Refer to the Mozilla Community Participation Guidelines.

I apologize for any rudeness in my remarks. I will be careful about what I say.

[robinmetral]

Amazing. I might be able to squeeze in a quick hotfix PR to the docs tonight (EU time). Unless you'd rather do this yourself—don't want to step on your feet.

A quick rephrasing will probably remove all misunderstandings here 🤗

[debiru]

Thank you for your understanding and cooperation. It is very helpful.

[robinmetral]

Thank you for starting the discussion and following up on it, clarity in these topics is important!

[robinmetral]

I opened mdn/content#21948, which should solve this issue (based on this discussion thread). Feedback welcome on the PR 🙏

[Rumyra]

Thanks so much both! I think the modifications made to the page in question have really helped to eliminate confusion