Using Heading Elements to Create a Document Outline

06 October 2015

The outline for an HTML document shows the structure of the content on the page. This is useful for user agents, who can use the outline to create, for example, a table of contents for the document. This can then be used by screen readers to help people better navigate the page.

The following markup, for example, will produce the following outline -

<h1>Using Heading Elements to Create a Document Outline</h1>

<h2>Use Each Heading Element to Define a New “Section"</h2>
<h2>Use the Heading Ranks to Specify Subsections</h2>
<h2>Use the <section> Element to Explicitly Define Section Barriers</h2>

1. Using Heading Elements to Create a Document Outline

  1. Use Each Heading Element to Define a New "Section"
  2. Use the Heading Ranks to Specify Subsections
  3. Use the <section> Element to Explicitly Define Section Barriers

Creating these outlines is the function of the heading elements - h1 ... h6 . They provide the title or “theme” for each section of the page, which can then be collated to create the outline.

In order to create an accurate and useful outline, we need to use the heading elements in a particular way.

Use Each Heading to Define a New "Section" #

The heading elements should only be used to specify the start and title of a new section of content. Heading elements are sometimes commonly (and wrongly) used to markup subheading or subtitles. They should in fact only be used to define the title of the following section of content.

If we imagine the end goal for the document outline - to create a table of contents - we see why this should be the case. If we want to define a subheading, there are other ways to do so that do not interfere with the document outline.

<header>
  <h1>Page Title</h1>
  <h2>Subtitle</h2>
</header>

Incorrect method

<header>
  <h1>Page Title</h1>
  <p class="subheading">Subtitle</p>
</header>

Correct method

Use the Heading Ranks to Specify Subsections #

There are six levels (or “ranks”) of headings - h1, h2, h3, h4, h5, and h6. The rank for each of the headings should be used to define subsections within broader sections.

Headings of the same level imply equal rank on the page. For example, this page will produce the following outline -

<h1>Apples</h1>
<p>Apples are fruit.</p>

<h2>Varieties</h2>
<p>There are a number of different varieties of Apples</p>

<h3>Braeburn</h3>
<p>About these type of apples</p>

<h3>Royal Gala</h3>
<p>About these type of apples</p>

<h3>Pink Lady</h3>
<p>About these type of apples</p>

<h2>Taste</h2>
<p>They tast lovely.</p>

<h2>Colour</h2>
<p>Apples come in a variety of colours</p>

1. Apples
  1. Varieties
    1. Braeburn
    2. Royal Gala
    3. Pink Lady
  2. Taste
  3. Colour

Use the `<section>` Element to Explicitly Define Section Barriers #

In HTML5, a new way of creating an outline was introduced. It was introduced that nesting <section> elements and using only h1 could be used to define subsections, instead of using the different heading ranks.

For example, to create the same outline from the Apple document above, we can instead write -

<section>
  <h1>Apples</h1>
  <p>Apples are fruit.</p>

  <section>
    <h1>Varieties</h1>
    <p>There are a number of different varieties of Apples</p>

    <section>
      <h1>Braeburn</h1>
      <p>About these type of apples</p>
    </section>

    <section>
      <h1>Royal Gala</h1>
      <p>About these type of apples</p>
    </section>

    <section>
      <h1>Pink Lady</h1>
      <p>About these type of apples</p>
    </section>
  </section>

  <section>
    <h1>Taste</h1>
    <p>They tast lovely.</p>
  </section>

  <section>
    <h1>Colour</h1>
    <p>Apples come in a variety of colours</p>
  </section>
</section>

Not currently recognised by user agents

This alternative method more easily allows us to change the nest levels without it having an effect on the rest of the document. However, this method is currently not recognised by any browsers or assitive technology user agents.

Using the above <section>-based document structure, most browsers will generate the following outline -

1. Apples
2. Varieties
3. Braeburn
4. Royal Gala
5. Pink Lady
6. Taste
7. Colour

Therefore, it is advised that we still use the appropriate heading rank, but in combination with the <section> element for future-proofing. Using the same example, we should instead write -

<section>
  <h1>Apples</h1>
  <p>Apples are fruit.</p>

  <section>
    <h2>Varieties</h2>
    <p>There are a number of different varieties of Apples</p>

    <section>
      <h3>Braeburn</h3>
      <p>About these type of apples</p>
    </section>

    <section>
      <h3>Royal Gala</h3>
      <p>About these type of apples</p>
    </section>

    <section>
      <h3>Pink Lady</h3>
      <p>About these type of apples</p>
    </section>
  </section>

  <section>
    <h2>Taste</h2>
    <p>They tast lovely.</p>
  </section>

  <section>
    <h2>Colour</h2>
    <p>Apples come in a variety of colours</p>
  </section>
</section>