What is document outline?

Document outline refers to the browser-generated structure of a HTML document. This structure is used to communicate meaning to the browser, the user and, most importantly, other technologies that are consuming the HTML, such as screen readers.

At the time of writing, the document outline of a web page is based only on the presence and ordering of the heading ranks h1 through to h6 and not sectioning elements such as <section> or <article>.

As a demonstration, refer to the following HTML which uses both sectioning elements and heading ranks to establish a document outline:

<!DOCTYPE html>
<head>...</head>
<body>
  <main>
    <h1>Heading</h1>
    <p>...</p>

    <section>
      <h2>Heading</h2>
      <p>...</p>

      <aside>
        <h3>Heading</h3>
        <p>...</p>
      </aside>
    </section>

    <section>
      <h2>Heading</h2>
      <p>...</p>
    </section>

    <section>
      <h2>Heading</h2>
      <p>...</p>
    </section>
  </main>
</body>
</html>

This HTML will produce the following outline:

1. Heading
  2. Heading
     3. Heading
  2. Heading
  2. Heading

A commonly held thought of mine was that sectioning elements would contribute to the document outline in addition to heading rankings, meaning sectioning elements would be used in conjunction with heading ranks when determining a document's structure.

A document outline algorithm describing this behaviour has been in the HTML specification since 2008 but is not implemented by browsers and other vendors.

To illustrate how this algorithm would work, the HTML example from above has been modified to only use <h1> elements alongside the same sectioning elements:

<!DOCTYPE html>
<head>...</head>
<body>
  <main>
    <h1>Heading</h1>
    <p>...</p>

    <section>
      <h1>Heading</h1>
      <p>...</p>

      <aside>
        <h1>Heading</h1>
        <p>...</p>
      </aside>
    </section>

    <section>
      <h1>Heading</h1>
      <p>...</p>
    </section>

    <section>
      <h1>Heading</h1>
      <p>...</p>
    </section>
  </main>
</body>
</html>

The document outline of this markup will now be:

1. Heading
1. Heading
1. Heading
1. Heading
1. Heading

Despite the presence of sectioning elements, they are ignored by the browser. This is not helpful to assistive technologies as the heading ranking semantics become lost and the content structure becomes unclear.

It is uncertain if the document outline algorithm will ever be implemented but the general rule for now is to presume that it doesn't and rely solely on heading rankings.

Further reading

A complete history of the document outline has been written in great detail by Amelia Bellamy-Royds on CSS-Tricks. This is highly recommended for those that want a deeper-dive into document outlines that looks beyond headings and sectioning elements.

Works cited

"HTML Standard." Web Hypertext Application Technology Working Group (WHATWG), 11 November 2019, https://html.spec.whatwg.org/multipage/sections.html#outlines. Accessed 16 November 2019.

Faulkner, Steve. "The HTML5 Document Outline." TPG – The Accessibility Experts, 28 October 2013, https://developer.paciellogroup.com/blog/2013/10/html5-document-outline/. Accessed 16 November 2019.

Robinson, Mike. "Document Outlines." HTML5 Doctor, 12 July 2011, http://html5doctor.com/outlines/. Accessed 16 November 2019.

"Using HTML sections and outlines." MDN, 31 October 2019, https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines. Accessed 16 November 2019.

Faulkner, Steve. "Computer says NO to HTML5 document outline." HTML5 Doctor, 9 June 2016, http://html5doctor.com/computer-says-no-to-html5-document-outline/. Accessed 19 November 2019.