Rephrase single h1 as best practice

[robinmetral]

Description

See https://github.com/orgs/mdn/discussions/232 and specifically this comment.

Motivation

The docs for heading elements (h1–h6) is mixing up conforming to the HTML standard with following best practices. This can be misleading.

In a nutshell: while using multiple h1 elements on a page is allowed by the standard, it is not considered a best practice.

Additional details

Line comments with extra details below.

This PR is a quick rephrasing of the problematic paragraph (to hopefully make reviewing easier).

However, I believe that this page would need some major rework (mostly around structure):

• the "usage notes" bullet points lack context, are not commonly used on other pages, and duplicate information found later on the page (e.g. in the accessibility section)
• in the accessibility section, "navigation" and "nesting" could be grouped under a single heading—they essentially cover the same requirement but from different angles
• other concerns could be added to the accessibility section, such as (on top of my head):
  • don't use heading elements for non-heading content (e.g. for large text) (this is mentioned in "usage notes")
  • the counterpart of the above, don't use e.g. large text without a heading element for headings
  • headings essentially section content, and they should label sections accurately

Related issues and pull requests

Relates to discussion #232

[github-actions]

Preview URLs

• /en-US/docs/Web/HTML/Element/Heading_Elements

Flaws (1)

URL: /en-US/docs/Web/HTML/Element/Heading_Elements
Title: <h1>–<h6>: The HTML Section Heading elements
Flaw count: 1

• macros:
  • wrong xref macro used (consider changing which macro you use)

External URLs (1)

URL: /en-US/docs/Web/HTML/Element/Heading_Elements
Title: <h1>–<h6>: The HTML Section Heading elements

• https://adrianroselli.com/2016/08/there-is-no-document-outline-algorithm.html (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2022-10-30 17:02:17.748113)

[robinmetral]

Feedback and edits by maintainers are more than welcome. I'm not a native English speaker, so feel free to improve phrasing to make it sound nicer 🙂

[robinmetral]

Since this doesn't mention other obsolete global attributes such as color or border, I don't think it's necessary to mention align (which isn't even listed on the global attributes page).

[robinmetral]

Avoid 👉 Do not, because doing this is a failure WCAG 2.1 SC 1.3.1 Info and relationships

A note: the other way around (using font-size for heading-like content, instead of heading elements) is a more obvious failure of the SC. I think that this scenario (using heading elements for non-heading-like content, instead of font-size) also fails the SC, but if it doesn't, it surely fails 2.4.6 Headings and labels). I haven't added any of this to the docs in doubt, would need an accessibility specialist to double-check

[robinmetral]

Avoid 👉 Do not, because doing this is not conforming to the HTML standard:

Each heading following another heading lead in the outline must have a heading level that is less than, equal to, or 1 greater than lead's heading level.

[robinmetral]

Do not 👉 Avoid, because multiple h1 elements on a page is allowed by the standard.

I rephrased the paragraph and kept the mention of the outline algorithm (for now), since I expect that some authors might be asking themselves this question when visiting the page (because nested h1 elements are still found on a lot of tutorials/articles from before the outline algorithm was removed from the standard)

[Rumyra]

Thanks @robinmetral ! I think this really helps clear up the discussion and I'll add a note there 👍

[debiru]

Thanks @robinmetral

It is simpler and easier to understand than the two previous versions.
I have translated it into Japanese as soon as possible.