developer.paciellogroup.com

The HTML5 Document Outline

Steve Faulkner
3-4 minutes

pink unicorn with a rainbow of h1 elements trailing behindIs a concept that lives in the HTML specification, but is essentially a fiction in the real world. It is a fiction because user agents have not implemented it and there is no indication that any will.

  The HTML5 Document Outline is a dangerous fiction

It is dangerous because it can lead unsuspecting developers to think that using the nesting of heading elements in sectioning elements actually has some effect for users who consume heading semantics. Overwhelmingly the opposite is true. For example If you code a heading as a h1 element and nest it 5 deep in sectioning elements, the document outline leads us to believe that the heading will be a h6, back in the real world the heading is a h1.

<!DOCTYPE html>
...
<body>
<h1>heading text</h1>
 <section><h1><h2>heading text...
  <section><h1><h3>heading text...
   <section><h1><h4>heading text...
    <section><h1><h5>heading text...
      <section><h1><h6>heading text...
      </section>
     </section>
   </section>
  </section>
</section>
</body>
 
<body>
<h1>heading text</h1>
 <section><h1>heading text
  <section><h1>heading text
   <section><h1>heading text
    <section><h1>heading text
      <section><h1>heading text...


<body>
<h1>heading text</h1>
 <section><h2>heading text...
  <section><h3>heading text...
   <section><h4>heading text...
    <section><h5>heading text...
      <section><h6>heading text...

Practical advice

If you as a developer want to provide a meaningful document structure, use the h1–h6 elements to express document structure. DO NOT rely upon the HTML5 document outline. By all means use the HTML5 section elements, but do not rely upon them to convey a meaningful structure. If at some point in the future the HTML5 document outline ceases to be a fiction, you will be covered as the use of h1-h6 is backwards compatible.

The advice in the HTML specification is clear on this:

Sections may contain headings of any rank, and authors are strongly encouraged to use headings of the appropriate rank for the section’s nesting level.

There is now (16/04/14) a warning in section 4.3.10.1 Creating an outline of the HTML spec

There are currently no known implementations of the outline algorithm in graphical browsers or assistive technology user agents, although the algorithm is implemented in other software such as conformance checkers. Therefore the outline algorithm cannot be relied upon to convey document structure to users. Authors are advised to use heading rank (h1–h6) to convey document structure.

If you don’t think it is clear enough, please file a bug.

Further reading