A Perfect Outline

Point Out Your Content: Utilize the HTML5 Outline-Algorithm

HTML5 introduces new semantic elements accompained by the definition of a new algorithm to calculate the document-outline from the mark up. There are plenty of good explanations of these new possibilities, to point out your content in a more controlled way. But the most of these explanations fall short, if it comes to how to put these new markup into use, so that it results in a sensible outline of the document, that was marked up.

In this article I will try to explain, how to use the new semantic markup, to produce an outline, that is usable as a real content table of the document – not just as an partially orderd overview of all headings. I will do so, by showing simple examples, that will illuminate the principles behind the new markup.

All Messed Up!

Although, the ideas behind the new markup seems to be simple and clear, nearly nobody accomplishes to produce a sensible outline. Even the big players, who guide us through the jungle of the new specifications and are giving great explanations about the subject, either fail on there sites (see by yourself with the help of the help of the h5o HTML5 Outline Bookmarklet), or produce the outline in the old way by the usage of h1–h6 only, like the fabulous HTML5-bible Dive Into HTML5.

This is, because there is a lot to mix up in a wrong way, when trying to adopt the new features. Here is, what I ended up with, on my first try to combine what I have learned about semantic elements and the document outline:

Example 01: Markup


<!DOCTYPE html>
<title>Example 01</title>
<header>
  <h2>Header</h2>
  <nav>Navigation</nav>
</header>
<main>
  <h1>Main</h1>
  <section>
    <h2>Section I</h2>
  </section>
  <section>
    <h2>Section II</h2>
    <section>
      <h3>Subsection a</h3>
    </section>
    <section>
      <h3>Subsection b</h3>
    </section>
  </section>
  <section>
    <h2>Section III</h2>
    <section>
      <h3>Subsection a</h3>
    </section>
  </section>
</main>
<aside>
  <h1>Aside</h1>
</aside>
<footer>
  <h2>Footer</h2>
</footer>

Example 01: Outline

  1. Header
    1. Untitled section
  2. Main
    1. Section I
    2. Section II
      1. Subsection a
      2. Subsection b
    3. Section III
      1. Subsection a
    4. Aside
    5. Footer

View example 01

That quiet was not the outline, that I had expected. I planed, that Header, Main, Aside and Footer are ending up at the same level. Instead of that, Aside and Footer had become sections of my Main-content. And where the hell comes that Untitled section from?!? My first thought on that was: No problem, I just forgot the header-tags. But after adding them, the only thing that cleared out, was where the Untitled section was coming from:

Example 02: Markup


<!DOCTYPE html>
<title>Example 02</title>
<header>
  <h2>Header</h2>
  <nav>
    <header><h3>Navigation</h3></header>
  </nav>
</header>
<main>
  <header><h1>Main</h1></header>
  <section>
    <header><h2>Section I</h2></header>
  </section>
  <section>
    <header><h2>Section II</h2></header>
    <section>
      <header><h3>Subsection a</h3></header>
    </section>
    <section>
      <header><h3>Subsection b</h3></header>
    </section>
  </section>
  <section>
    <header><h2>Section III</h2></header>
    <section>
      <header><h3>Subsection a</h3></header>
    </section>
  </section>
</main>
<footer>
  <header><h2>Footer</h2></header>

Example 02: Outline

  1. Header
    1. Navigation
  2. Main
    1. Section I
    2. Section II
      1. Subsection a
      2. Subsection b
    3. Section III
      1. Subsection a
    4. Aside
    5. Footer

View example 02

So I thought: Maybe the main-tag was the wrong choice. Perhaps it should be replaced by an article. But after that change, the outline even got worse. Now, Navigation, Main and Aside appeared on the same level, all as a subsection of Header. At least, Footer suddenly was a sibling of Header as planed:

Example 03: Markup


<!DOCTYPE html>
<title>Example 03</title>
<header>
  <h2>Header</h2>
  <nav>
    <header><h3>Navigation</h333></header>
  </nav>
</header>
<article>
  <header><h1>Article (Main)</h1></header>
  <section>
    <header><h2>Section I</h2></header>
  </section>
  <section>
    <header><h2>Section II</h2></header>
    <section>
      <header><h3>Subsection a</h3></header>
    </section>
    <section>
      <header><h3>Subsection b</h3></header>
    </section>
  </section>
  <section>
    <header><h2>Section III</h2></header>
    <section>
      <header><h3>Subsection a</h3></header>
    </section>
  </section>
</article>
<footer>
  <header><h2>Footer</h2></header>
</footer>

Example 03: Outline

  1. Header
    1. Navigation
    2. Main
      1. Section I
      2. Section II
        1. Subsection a
        2. Subsection b
      3. Section III
        1. Subsection a
    3. Aside
  2. Footer

View example 03

After that, I was totally confused and decided, to sort it out step by step. That procedure finally gave me the clue, I want to share with you now.

Step by Step (Uh Baby!)

Step I: Investigate the Structured Part

Let us start with the strictly structured part of the document: the article and it’s subsections. At first a minimal example with no markup except the article– and the section-tags:

Example 04: Markup


<!DOCTYPE html>
<title>Example 04</title>
<article>
  Main
  <section>
    Section I
  </section>
  <section>
    Section II
    <section>
      Subsection a
    </section>
    <section>
      Subsection b
    </section>
  </section>
  <section>
    Section III
    <section>
      Subsection a
    </section>
  </section>
</main>

Example 04: Outline

  1. Untitled BODY
    1. Untitled ARTICLE
      1. Untitled SECTION
      2. Untitled SECTION
        1. Untitled SECTION
        2. Untitled SECTION
      3. Untitled SECTION
        1. Untitled SECTION

View Example 04

Nothing really unexpected here. The article– and section-tags are reflected in the outline according to their nesting. The only thing notably here is, that the body itself is also reflected in the outline. It appears on its own level as the root-element of all tags. We can think of it as the title of our document.

We can add headings of any kind (h1–h6) here and will always get an identically structured outline, that reflects the text of our headings. If we want to give the body a title, we have to place a heading outside and before any sectioning-elements:

Example 05: Markup


<!DOCTYPE html>
<title>Example 05</title>
<h1>Page</h1>
<article>
  <h1>Article</h1>
  <section>
    <h1>Section I</h1>
  </section>
  <section>
    <h1>Section II</h1>
    <section>
      <h1>Subsection a</h1>
    </section>
    <section>
      <h1>Subsection b</h1>
    </section>
  </section>
  <section>
    <h1>Section III</h1>
    <section>
      <h1>Subsection a</h1>
    </section>
  </section>
</article>

Example 05: Outline

  1. Page
    1. Article
      1. Section I
      2. Section II
        1. Subsection a
        2. Subsection b
      3. Section III
        1. Subsection a

View Example 05

This is the new part of the outline algorithm introduced in HTML5: The nesting of elements, that define sections, defines the outline of the document. The rank of the heading element is ignored by this algorithm!

Among the elements, that define sections in HTML5 are the article and the section tags. But there are more. I will discuss them later. For now, you only have to know, that in HTML5, sectioning elements define the structure of the outline. Also, you should memorize, that the outline always has a single root without any siblings: the body.

Step II: Investigate the Page-Elements

So, let us do the same with the tags that represent the different logical sections of a web-page: the page-elements. We start with a minimal example again, that contains no markup except the header– the main and the footer-tags:

Example 06: Markup


<!DOCTYPE html>
<title>Example 06</title>
<header>Page</header>
<main>Main</main>
<footer>Footer</footer>

Example 06: Outline

  1. Untitled BODY

View Example 06

That is wired, ehh? There is only one untitled element in the outline. The explanation for this is, that neither the header– nor the main– nor the footer-tag belong to the elements, that define a section in HTML5! This is often confused, because these elements define the logical sections (header – main-content – footer) of a website. But these logical sections do not have to do anything with the structural sectioning of the document, that defines the outline.

Step III: Investigate the Headings

So, what happens, if we add the desired markup for our headings? We want a h1-heading for our main-content, because it is the important part of our page. The header should have a h2-heading and the footer a h3-heading, because it is rather unimportant.

Example 07: Markup


<!DOCTYPE html>
<title>Example 07</title>
<header><h2>Page</h2></header>
<main><h1>Main</h1></main>
<footer><h3>Footer</h3></footer>

Example 07: Outline

  1. Page
  2. Main
    1. Footer

View Example 07

Now, there is an outline again. But why? And why is it looking this way?

What happens here, is implicit sectioning. In short, implicit sectioning is the outline algorithm of HTML4. HTML5 needs implicit sectioning, to keep compatible with HTML4, which still dominates the web. In fact, we could have used plain HTML4, with div instead of header, main and footer, and it would have yield the exact same outline:

Example 08: Markup


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head><title>Example 08</title></head>
  <body>
    <div class="header"><h2>Page</h2></div>
    <div class="main"><h1>Main</h1></div>
    <div class="footer"><h3>Footer</h3></div>
  </body>
</html>

Example 08: Outline

  1. Page
  2. Main
    1. Footer

View Example 08

In HTML4, solely the headings (h1–h6) define the outline of a document. The enclosing elements or any nesting of them are ignored altogether. The level, at which a heading appears in the outline, is defined by the rank of the heading alone. (Strictly speaking, HTML4 does not define anything like a document outline. But as a result of the common usage and interpretation, this is, how people outline their documents with HTML4.)

The implicit sectioning of HTML5 works in a way, that is backward compatible with this way of outlining, but closes the gaps in the resulting hierarchy: Each heading implicitly opens a section – hence the name –, but if there is a gap between its rank and the rank of its ancestor – that is the last preceding heading with a higher rank – it is placed in the level directly beneath its ancestor:

Example 09: Markup


<!DOCTYPE html>
<title>Example 09</title>
<h4>h4</h4>
<h2>h2</h2>
<h4>h4</h4>
<h3>h3</h3>
<h2>h2</h2>
<h1>h1</h1>
<h2>h2</h2>
<h3>h3</h3>

Example 09: Outline

  1. h4
  2. h2
    1. h4
    2. h3
  3. h2
  4. h1
    1. h2
      1. h3

View Example 09

See, how the first heading h4 ends up on the same level as the second, which is a h2. Or, how the third and fourth headings are both on the same level under the h2, although they are of different rank. And note, how the h2 and h3 end up on different sectioning-levels as their earlier appearances, if they follow a h1 in the natural order.

Step IV: Mixing it all together

With the gathered clues in mind, we can now retry to layout our document with the desired outline. If we want, that Header, Main and Footer end up as top level citizens in our planed outline, we simply have to achieve, that they are all recognized as sections under the top level by the HTML5 outline algorithm. We can do that, by explicitly stating, that the header and the footer are section:

Example 10: Markup


<!DOCTYPE html>
<title>Example 10</title>
<header>
  <section>
    <h2>Main</h2>
  </section>
</header>
<main>
  <article>
    <h1>Article</h1>
    <section>
      <h2>Section I</h2>
    </section>
    <section>
      <h2>Section II</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
      <section>
        <h3>Subsection b</h3>
      </section>
    </section>
    <section>
      <h2>Section III</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
    </section>
  </article>
</main>
<footer>
  <section>
    <h3>Footer</h3>
  </section>
</footer>

Example 10: Outline

  1. Untitled BODY
    1. Main
    2. Article
      1. Section I
      2. Section II
        1. Subsection a
        2. Subsection b
      3. Section III
        1. Subsection a
    3. Footer

View Example 10

So far, so good. But what about the untitled body? We forgot about the single root of any outline, that is defined by the body, how we learned back in step 1. As shown in example 05, we can simply name that by putting a heading outside and before any element, that defines a section:

Example 11: Markup


<!DOCTYPE html>
<title>Example 11</title>
<header>
  <h2>Page</h2>
  <section>
    <h3>Header</h3>
  </section>
</header>
<main>
  <article>
    <h1>Article</h1>
    <section>
      <h2>Section I</h2>
    </section>
    <section>
      <h2>Section II</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
      <section>
        <h3>Subsection b</h3>
      </section>
    </section>
    <section>
      <h2>Section III</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
    </section>
  </article>
</main>
<footer>
  <section>
    <h3>Footer</h3>
  </section>
</footer>

Example 11: Outline

  1. Page
    1. Header
    2. Main
      1. Section I
      2. Section II
        1. Subsection a
        2. Subsection b
      3. Section III
        1. Subsection a
    3. Footer

View Example 11

Step V: Be Aware, Which Elements Define Sections

The eagle-eyed among you might have noticed, that I had “forgotten” the two element-types nav and aside, when we were investigating the elements, that define the logical structure of the page in step 2. I did not forgot about these – I left them out intentionally. Because otherwise, the results of example 07 would have been too confusing, to made my point about implicit sectioning. Let us look, what would have happend:

Example 12: Markup


<!DOCTYPE html>
<title>Example 12</title>
<header>
  <h1>Page</h1>
  <nav><h1>Navigation</h1></nav>
</header>
<main><h1>Main</h1></main>
<aside><h1>Aside</h1></aside>
<footer><h1>Footer</h1></footer>

Example 07: Outline

  1. Page
    1. Navigation
  2. Main
    1. Aside
  3. Footer

View Example 12

What is wrong there? Why are Navigation and Aside showing up as children, albeit we marked up every element with headings of the same rank? The reason for this is, that nav and aside are sectioning elements:

Example 12: Markup


<!DOCTYPE html>
<title>Example 13</title>
<header>
  Page
  <nav>Navigation</nav>
</header>
<main>Main</main>
<aside>Aside</aside>
<footer>Footer</footer>

Example 07: Outline

  1. Untitled BODY
    1. Untitled NAV
    2. Untitled ASIDE

View Example 13

The HTML5 spec defines four sectioning elements: article, section, nav and aside! Some explain the confusion about this fact with the constantly evolving standard, that leads to structurally unclear specifications. I will be frank: I cannot imagine any good reason for this decision! In my opinion, the concept would be much clearer, if article and section would be the only two sectioning elements and nav and aside would only define the logical structure of the page, like header and footer.

Putting It All Together

Knowing, that nav and aside will define sections, we now can complete our outline skillfully avoiding the appearance of untitled sections:

Example 14: Markup


<!DOCTYPE html>
<title>Example 14</title>
<header>
  <h2>Page</h2>
  <section>
    <h3>Header</h3>
    <nav><h4>Navigation</h4></nav>
  </section>
</header>
<main>
  <article>
    <h1>Main</h1>
    <section>
      <h2>Section I</h2>
    </section>
    <section>
      <h2>Section II</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
      <section>
        <h3>Subsection b</h3>
      </section>
    </section>
    <section>
      <h2>Section III</h2>
      <section>
        <h3>Subsection a</h3>
      </section>
    </section>
  </article>
</main>
<aside><h3>Aside</h3></aside>
<footer>
  <section>
    <h3>Footer</h3>
  </section>
</footer>

Example 14: Outline

  1. Page
    1. Header
      1. Navigation
    2. Main
      1. Section I
      2. Section II
        1. Subsection a
        2. Subsection b
      3. Section III
        1. Subsection a
    3. Aside
    4. Footer

View Example 14

Et voilà: Our Perfect Outline!

If you memorize the concepts, that you have learned in this little tutorial, you should now be able to mark up your documents to generate your perfect outline…

…but: one last word about headings:

A Word On The Ranks Of The Headings

It is crucial to note, that the new outline-algorithm still is a fiction: most user agents do not implement the algorithm yet. Hence, you still should stick to the old hints for keeping your content accessible and point out the most important heading to the search engines.

But there is no reason, not to apply the new possibilities shown in this article to your markup: it will only make it more feature-proof. It is very likely, that search engines will start to adopt the HTML5 outline algorithm, to make more sense out of your content in near feature – or are already doing so… So, why not be one of the first, to gain from that new technique.

I would advise you, to adopt the new possibilities to section your content and generate a sensible outline, while still keeping the old heading ranks to be backward compatible.

Comments / Questions

  1. Izhari Ishak Aksa says:
    April 10, 2020 at 11:53

    I think main navigation should be right below the page. Furthermore each section could also have their own navigation. For example in a product page there could navigation for specs, reviews, description etc.

    Reply
  2. bijibuji says:
    April 18, 2019 at 18:56

    What is the exact use case of “Page” & “Main” titles according to a single blog page. Is “Page” the website name or the single blog title? What about “Main”? Also how do you deal with starting the page with an heading as it is not valid (using W3C validator tells you that you have a missing in your heading-level outline)

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *