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.

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.









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 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

[code type=html]

Bob Dylan Albums
Some text


Blood on the Tracks
Some text



Highway 61 Revisited
Some text


Some text

[/code]

The HTML produces the following outline.

[code type=html]
1. Bob Dylan Albums
1.1 Blood on the Tracks
1.2 Highway 61 Revisited
[/code]

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

[code type=html]

Bob Dylan Albums
Some text


Blood on the Tracks
Some text



Highway 61 Revisited
Some text


Some text

[/code]

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

[code type=html]
1. Document
1.1 Bob Dylan Albums
1.1.1 Blood on the Tracks
1.1.2 Highway 61 Revisited
[/code]

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.

HTML5 Outliner

HTML 5 Outliner

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:

[code type=html]
1. Bob Dylan Albums

1.1 Blood on the Tracks

1.2.Highway 61 Revisited

[/code]

Using sections:

[code type=html]
1. Document
1.1 Bob Dylan Albums

1.1.1 Blood on the Tracks

1.1.2 Highway 61 Revisited

[/code]

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 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.

[code type=html]


Bob Dylan Albums



Blood on the Tracks




Highway 61 Revisited

[/code]

The code produces this, perhaps surprising, outline.

[code type=html]
1. Document
1.1 Section

1.1.1 Bob Dylan Albums

1.1.2 Blood on the Tracks

1.2 Highway 61 Revisited

[/code]

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.

[code type=html]


Bob Dylan Albums



Blood on the Tracks




Highway 61 Revisited

[/code]

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

[code type=html]
1. Bob Dylan Albums
1.1 Blood on the Tracks
1.2 Highway 61 Revisited
[/code]

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.

[code type=html]

Heading level 1
Heading level 3



Heading level 3
Heading level 1

[/code]

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.

[code type=html]
1.Document
1.Heading level 1
1.Heading level 3
2.Heading level 3
3.Heading level 1
[/code]

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.

[code type=html]

Bob Dylan Albums

Bringing it all Back Home

Blonde on Blonde

[/code]

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

[code type=html]
1.Document
1.1 Bob Dylan Albums
1.1.1 Blonde on Blonde
[/code]

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 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.