Skip to content
This repository has been archived by the owner on Jan 24, 2024. It is now read-only.

Misleading usage notes for Heading elements #3652

Closed
1 of 3 tasks
DefiCzech opened this issue Sep 2, 2020 · 6 comments
Closed
1 of 3 tasks

Misleading usage notes for Heading elements #3652

DefiCzech opened this issue Sep 2, 2020 · 6 comments

Comments

@DefiCzech
Copy link

DefiCzech commented Sep 2, 2020

Request type

  • Please close this issue, I accidentally submitted it without adding any details
  • New documentation
  • Correction or update

Details

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

In Usage notes for Heading elements is

You should only use one <h1> per page. Using more than one will not result in an error, but using only one is seen as a best practice. It makes logical sense — <h1> is the most important heading, and tells you what the purpose of the overall page is. You wouldn't have a book with more than one title, or a movie with more than one name! Having a single top-level title is also arguably better for screenreader users, and SEO.

https://html.spec.whatwg.org/#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements look at first example

<body>
 <h1>Let's call it a draw(ing surface)</h1>
 <section>
  <h1>Diving in</h1>
 </section>
 <section>
  <h1>Simple shapes</h1>
 </section>
 <section>
  <h1>Canvas coordinates</h1>
  <section>
   <h1>Canvas coordinates diagram</h1>
  </section>
 </section>
 <section>
  <h1>Paths</h1>
 </section>
</body>

it makes more sense then only one <h1> on page. In development if you have independent component is impossible to achieve proper heading levels, because you dont know where the component will be nested.

Even example is missleading

You wouldn't have a book with more than one title, or a movie with more than one name!

because title of book is in <title> element not in <h1> element.

@sideshowbarker
Copy link

The guidance in MDN about not using more than one h1 per page isn’t an oversight or mistake — it’s very intentional. And that guidance is based on the fact that the so-called outline algorithm in the HTML spec isn’t actually implemented in browsers; that is, the algorithm at https://html.spec.whatwg.org/multipage/sections.html#outlines

In order to handle multiple h1 elements on a page as expected, a browser needs to implement the outline algorithm. But because there are no browsers that implement the outline algorithm, there are no browsers that handle multiple h1 elements as expected.

Therefore, the MDN article contains that warning against using multiple h1 elements per age — and also the W3C HTML checker (validator) emits a warning for any documents that have more than one h1 element per page.

It’s true that — despite all the above being the case — the HTML spec still contains examples that show using multiple h1 elements per page. But that’s a well-known, longstanding problem with those parts of the spec not matching reality — and at whatwg/html#3499 there’s an open pull request for fixing that problem — including a change to those multiple-h1-per-document examples. But there are also some problems with that pull request which have prevented it from being landed yet.

In the mean time, MDN continues to contain a warning about not using multiple h1 elements per page — because doing that continues to not be recommended in practice (due to the fact that no browsers actually implement that outline algorithm, as mentioned above).

See https://developer.paciellogroup.com/blog/2013/10/html5-document-outline/ for a more-detailed explanation.

@DefiCzech
Copy link
Author

DefiCzech commented Sep 2, 2020

Ok makes sense, that there is no outline algorithm for sectioning elements. Thank you for enlightening.

What? W3C HTML checker emits a warning for any documents that have more then one h1 element? Where in specification is mention about this kind of limitation?

I just dont understand what is wrong for user with these kind of outline.

<title>Travel agency</title>

<h1>Greece</h1>
<h2>Interesting places</h2>
<h2>Weather</h2>

<h1>Thailand</h1>
<h2>Interesting places</h2>
<h3>Land</h3>
<h3>See</h3>

There should not be any limitation of how many h1, h2 etc. you can use in your document.

@sideshowbarker
Copy link

I just dont understand what is wrong for user with these kind of outline.

<title>Travel agency</title>

<h1>Greece</h1>
<h2>Interesting places</h2>
<h2>Weather</h2>

<h1>Thailand</h1>
<h2>Interesting places</h2>
<h3>Land</h3>
<h3>See</h3>

So in the case, what is the actual overall top-level heading for the entire page?

What is that page about? What do each of the Greece, Thailand, etc., subsections relate to?

As far as I can see, that page doesn’t have an overall top-level heading that indicates how the subsections are related to each other. So that’s potentially confusing for someone visiting the page for the first time — and especially potentially confusing to screen-reader users.

To be clear about one thing: The <title>Travel agency</title> content is never rendered in the document itself, so simply putting the overall document title only in the title element is not sufficient.

So because the above example lacks any rendered document title — it lacks an overall top-level heading — I think most web markup practitioners would say that is not best-practice.

Best practice would be to add a single overall top-level heading/title for the document; for example:

<h1>Popular travel destinations</h1>

<h2>Greece</h2>
<h3>Interesting places</h3>
...

<h2>Thailand</h2>
<h3>Interesting places</h3>
...

@DefiCzech
Copy link
Author

I my case there is no actual overall top-level heading. Page title is in <title> tag (name whole page).

What I am telling is that on same pages more than one <h1> makes sense - especially on homepages. Because on homepages you are forced to use one unnecessary (in most cases not presented to user) <h1> to create valid heading structure. Or in some cases title and <h1> are with same text etc. For me it is bad practice - hide <h1>.

If only one <h1> is valid for page so there is not difference between <title> (only one must be in page) and <h1> (only one should be in page based on MDN text) excpet <title> is not rendered in page and <h1> is.

@sideshowbarker
Copy link

It’s worth noting the MDN article language cited in the issue description doesn’t say, You must never use more than one h1 per page. Instead that statement very intentionally uses the word should and mentions best practice.

So that wording as currently written already allows for the possibility that there are some cases when it might make sense for a page to have more than one h1 element — and there are some developers who know very well what they are doing and who can choose to use more than h1 per page when that makes sense to them.

But the article is attempting to give guidance to developers who don’t necessarily know quite a well what they are doing — and that’s why they are coming to MDN; they are looking for guidance about what common best practices for using headings.

And so, the MDN article is optimized for that kind of developer — it’s written for the common case. It’s intended to help developers avoid inadvertently making a mistake due to lack of basic understanding of how h1-h6 headings are meant to be used hierarchically to structure a page — and that in most cases, it makes sense for every page to have a single top-level heading that tells readers: This page overall is about foo, where foo is the topic of the page overall.

@DefiCzech
Copy link
Author

Understood. Thank you for clarification. I am closing this issue.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants