The HTML5 Document Outline

The HTML 4 document outline, while easy to understand, has a few issues. It doesn’t allow for tangential content and it can be difficult to merge content from multiple documents. The HTML5 document outline and the new structural elements solve those problems in theory.

An HTML document

Last week I began a look at the HTML5 outline and the new elements by looking at the HTML 4 document outline for context. I also talked about some of the problems with the outline and whether or not we should bother with the HTML5 document outline as it will probably never be in use.

I think the HTML5 outline can still serve as context for trying to understand how to use new semantic elements like, section, article, aside, nav, header, and footer and it’s useful in that context. Today I’ll walk through the HTML5 document outline and how it’s supposed to work.

Next week we’ll get a little more in-depth about the new elements. I want to look at how each is defined in the spec as well as the use cases given to offer guidance for using the new elements. I also want to look at the ARIA roles each of the new elements maps to to further understand how to use the new elements in practice.

HTML5 Document Outline

The document outline we worked with prior to HTML5 (and still work with today) isn’t bad. It seems to have worked pretty well all these years, even if it’s not without some problems.

You can’t always tell whether content belongs to a subsection or it’s parent section. Wrapping content with divs can help, but the divs offer no semantics without additional class or id names.

Because everything is in a section in the document outline, it can be hard to account for information that’s related to the content in the main outline, but isn’t truly a part of it.

It’s also difficult to take modular content from different documents and merge them into a single document. Content from one of the original documents will likely need to revisit it’s heading structure and tweak it so the merged content fits within the combined structure.

The HTML5 document outline solves these problems with a new algorithm and some new sectioning elements that can be used to explicitly define a new section in the outline.

  • <section>
  • <article>
  • <aside>
  • <nav>

Note: The main, header, and footer elements are not sectioning elements.

Any of these four elements starts a new section of the outline within the parent element. The idea is to create a more understandable and logical structure, with better semantics.

For example <section> is meant to contain chunks of related content. It’s the most generic of the new elements. We could replace the divs from one of last week’s examples with section elements.

Here’s the example from last week

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<div>
  <h1>Bob Dylan Albums</h1>
  <p>Some text</p>

  <div>
    <h2>Blood on the Tracks</h2>
    <p>Some text</p>
  </div>

  <div>
    <h2>Highway 61 Revisited</h2>
    <p>Some text</p>
  </div>

  <p>Some text</p>
</div>

The HTML produces the following outline.

1
2
3
1. Bob Dylan Albums
   1.1 Blood on the Tracks
   1.2 Highway 61 Revisited

We can replace all of the divs with section elements and produce a new outline.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<section>
  <h1>Bob Dylan Albums</h1>
  <p>Some text</p>

  <section>
    <h2>Blood on the Tracks</h2>
    <p>Some text</p>
  </section>

  <section>
    <h2>Highway 61 Revisited</h2>
    <p>Some text</p>
  </section>

  <p>Some text</p>
</section>

This example may look similar to the previous one using divs, but it does result in a slightly different outline.

1
2
3
4
1. Document
   1.1 Bob Dylan Albums
       1.1.1 Blood on the Tracks
       1.1.2 Highway 61 Revisited

The outline has a new section at the top called Document. It’s created by the initial sectioning element that wraps everything, which is the body element.

Note: You can use either of the outliners below to check the document outline for your HTML. I’ll be using the first one throughout the series.

Here are both outlines again, along with the elements that create the new sections. It’s a useful feature of the first outliner and one reason I’m using it.

Using divs:

1
2
3
1. Bob Dylan Albums <body><h1>
   1.1 Blood on the Tracks <h2>
   1.2.Highway 61 Revisited <h2>

Using sections:

1
2
3
4
1. Document<body>
   1.1 Bob Dylan Albums <section><h1>
       1.1.1 Blood on the Tracks <section><h2>
       1.1.2 Highway 61 Revisited <section><h2>

Divs don’t signal a new section. They may be structural or they may be presentational. Section elements always signal a new section. This is true of all the sectioning elements and not just the <section> element.

When using sections the heading is responsible for the text shown in the outline, but it’s the section element that’s responsible for creating the section.

Here I’ve reworked the example a bit. I removed the paragraphs and changed the structure a little by wrapping the h1 in its own section and then wrapping it and first h2 in another section.

1
2
3
4
5
6
7
8
9
10
11
12
13
<section>
  <section>
    <h1>Bob Dylan Albums</h1>
  </section>

  <section>
    <h2>Blood on the Tracks</h2>
  </section>
</section>

<section>
  <h2>Highway 61 Revisited</h2>
</section>

The code produces this, perhaps surprising, outline.

1
2
3
4
5
1. Document <body>
   1.1 Section <section>
       1.1.1 Bob Dylan Albums <section><h1>
       1.1.2 Blood on the Tracks <section><h2>
   1.2 Highway 61 Revisited <section><h2>

Once again the top of the outline (Document) is created by the body not shown in the code. The untitled Section comes from the section element that wraps both the h1, Bob Dylan Albums and the h2, Blood on the Tracks. Note that both are at the same level of the hierarchy.

Regardless of the specific level heading used, the first heading inside a section is the main heading for that section. This is why both Bob Dylan Albums and Blood on the Tracks are at the same level in the in the outline. Both are the first heading in their respective sections.

Also note that Highway 61 Revisited jumps back up one level in the outline. I’ll explain this momentarily, but first let’s compare the example to one using divs instead of sections.

1
2
3
4
5
6
7
8
9
10
11
12
13
<div>
  <div>
    <h1>Bob Dylan Albums</h1>
  </div>

  <div>
    <h2>Blood on the Tracks</h2>
  </div>
</div>

<div>
  <h2>Highway 61 Revisited</h2>
</div>

Using divs produces the same document outline as before, despite the code using a different HTML structure.

1
2
3
1. Bob Dylan Albums
    1.1 Blood on the Tracks
    1.2 Highway 61 Revisited

Implicit Sectioning

The first heading (regardless of it’s level) inside a sectioning element is the main heading for that sections. What about multiple headings inside a section. Headings that follow the first also create new sections like they do in HTML 4, but these sections are implied sections as no new sectioning element is introduced.

Consider the following code.

1
2
3
4
5
6
7
8
9
<section>
<h1>Heading level 1</h1>
<h3>Heading level 3</h3>
</section>

<section>
<h3>Heading level 3</h3>
<h1>Heading level 1</h1>
</section>

Here I have two sections. Inside each section is an h1 and an h3, but they’re in reverse order in the two sections. The code produces this outline.

1
2
3
4
5
1.Document
     1.Heading level 1
         1.Heading level 3
     2.Heading level 3
     3.Heading level 1

The outline probably wasn’t what you were expecting. Once again the top of the outline is created by the body element (not shown).

The first section nests the h3 one level below the h1, which is probably close to what you would expect. However, in the second section both headings are at the same level in the outline.

The h1 in the first section and the h3 in the second are at the same level in the hierarchy, because each is the first heading inside its section. Each is effectively an h1 despite one being written as an h3.

The second heading inside each section also creates a new section. The section is implied, since there is no new sectioning element.

When the h3 follows the h1, the h3 is nested one level down. When the h1 follows the h3, the h1 stays at the same level in the hierarchy. Remember the h3 in the second section is acting as the top level heading (h1) for the section. Despite the actual heading used, the document outline sees two top level headings.

This behavior is to ensure backwards compatibility with all the HTML 4 on the web. You’ve seen the difference in the outline when using divs and sections.

Any heading that isn’t the first heading of its parent sectioning element becomes a new implicit section according to three rules.

  • If the second heading is of lower rank (h3 vs h1 in the example), it becomes an implicit subsection.
  • If the headings are the same level, the first section is closed (explicit or implicit) and a new implicit section at the same level is started.
  • If the second heading is a higher level (h1 to h3 in the the example) the section (explicit or implicit) is a closed and a new implicit section starts one level higher in the outline.

The last rule explains why the h2, Highway 61 Revisited jumped up a level in the example from earlier in this post.

The specific headings used aren’t relevant. It’s the differences between them that are. Had I used h1s and h4s or h2s and h6s, the outline would be the same.

Sectioning Roots

Sectioning roots are HTML elements that create a new section on a separate outline. Sections inside a sectioning root don’t contribute to the main outline of ancestor elements. The body tag is a sectioning root without an ancestor.

Other section roots are:

  • blockquote
  • figure
  • details
  • fieldset
  • td

In the following example, the blockquote is a sectioning root and so it’s content won’t be included in the main document outline.

1
2
3
4
5
6
7
<section>
  <h1>Bob Dylan Albums</h1>
  <blockquote>
     <h1>Bringing it all Back Home</h1>
  </blockquote>
  <h2>Blonde on Blonde</h2>
</section>

As you can see the resulting outline doesn’t include Bringing it all Back Home.

1
2
3
1.Document
  1.1 Bob Dylan Albums
       1.1.1 Blonde on Blonde

Closing Thoughts

I covered how the HTML5 document outline is meant to work. Again it isn’t currently implemented anywhere and probably never will be. The outline does provide the context for using the new elements, though.

Hopefully the examples here help make the outline a little clearer. If not use one of the outline checking tools I linked to earlier in the post. You can test my code or better test some of your own.

A new section can be created explicitly with any of the new sectioning elements. I only used the <section> element in the examples to focus on the outline rather than the elements, but the other sectioning elements (article, nav, aside) will also create new explicit sections.

A new section can be created implicitly with hx tags. The first heading inside a section will always be the main heading for the section and will effectively be an h1. Headings that follow start new implicit sections inside the parent.

Sectioning roots such as a blockquote or figure also create new sections, however these sections are separate from the main document outline.

Again if this still isn’t clear test some code in either of the tools I linked to. Testing your own code really is the best way to understand what’s going on.

Next week I’ll continue and talk about all of the new structural elements. We’ll look at four sectioning elements (section, article, nav, and aside) and three non-sectioning elements (header, footer, and main). Each has a specific purpose beyond whether it does or doesn’t create a new section.

Download a free sample from my book, Design Fundamentals.

11 comments

    • Thanks Paul. I do know. I wanted to look at the outline to see if I could gain some context when working with the new structural elements.

      I found the confusing in practice and based on a comment on a previous post I decided to look through the document outline.

      It turned into a longer series about the elements followed by a demo with me talking about why I did or didn’t structure something a certain way.

      Thanks for the link. I thought I had included it in this post, but I don’t see. I know I had the page open while researching.

  1. Great article, thanks for the in depth explanation. It really helped give me an applicable use for html5. I’ve tried implementing it but it hasn’t stuck so hopefully the section element will help with that.

    • Thanks Jared. Just keep in mind this isn’t implemented anywhere and isn’t like to be implemented anywhere in the future. I’m looking at the outline for context about the elements, which I’ll start talking about next week.

  2. Not sure why it would still be called a “document”. Aren’t we passed the days of documents and more on to the days of apps? Seems like replacing “document”, with “application” or just “frame” would be more semantic. That’s just my two cents. :/

  3. Thanks for the article but I’m confused by talk of browser implementation – why would that even matter? Surely problems would only occur if search engines started implementing this. Ok, you pointed out that no-one is likely to implement this ever and hopefully this stays purely hypothetical but, by way of example, I’m just now writing a new accordion feature for my company’s web-site and thought of using article and detail tags; but if the detail tag starts a new section root what might Google do with that if they did decide to implement the document outline? Ignore the content? Give the content less weight for its page ranking? Treat the content as if it were several pages? Anyway, it sounds like it’s better not to use the new “semantic” tags at all!
    Looking forward to your follow-up article 🙂

    • Thanks Kaya.

      It’s not so much that anything will go wrong or there will be problems. I just didn’t want anyone to think browsers would interpret a document in this way. You’re fine using articles and details.

      This post and the last one are really context for the next few. For a few reasons I found some of the new elements confusing to use. I thought writing through it would help. Forcing myself to write something forces me to spend more time understanding it first.

  4. Good read, but I, and I’m sure there are many like me, find it hard to figure out when something should be in a section, div, article or whatever. This can take really some time depending on the size of a project and I find it also hard to explain to clients of the importance of it, because 9 out of 10 times they don’t share this way of thinking. They look at there budget… and say “no don’t put much (or any) time in that. If it looks good we’re happy”
    I’m not saying I put everything in a div, but I have to decide really quick and use what I think should be used for that piece of content, while I should perhaps use something different.
    More semantics, makes it also more confusing and not to mention the ARIA roles I could ore even should add to it as well.

    • Hopefully the remainder of this series will help. Today I started talking about the definitions for the new elements. I’ll continue that next week and then present a demo for a few weeks to talk about how I used the elements.

Leave a Reply

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