Updated 21/01/2014 by Dr. Steve
Document outlines have changed a bit in HTML5. For a start, they’re actually in the spec (and have been for years – (2008). The HTML5 Doctor is here to explain what document outlines are, how to make good ones, and why you should care.What are document outlines? #
The document outline is the structure of a document, generated by the document’s headings, form titles, table titles, and any other appropriate landmarks to map out the document. The user agent can apply this information to generate a table of contents, for example. This table of contents could then be used by assistive technology to help the user, or be parsed by a machine like a search engine to improve search results. The outlining algorithm has been clearly defined in the HTML5 spec, so once all browsers and assistive technologies play ball, there will be some major accessibility wins (more on support later). Before we take a look at how this new algorithm works, it’s time for a quick walk down memory lane.Outlines in HTML4 #
Creating document outlines prior to HTML5 was simple. You had six heading elements,<h1> through <h6>. Lower-numbered headings were of a higher rank of higher-numbered ones — i.e. <h1> was ranked higher than <h2>:
<h1>My fantastic site</h1>
<h2>About me</h2>
<p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
<h3>What I do for a living</h3>
<p>I sell enterprise-managed ant farms.</p>
<h2>Contact</h2>
<p>Shout my name and I will come to you.</p>
- My fantastic site
- About me
- What I do for a living
- Contact
- About me
<h2> titles are children of the <h1>, and the “About me” content has a further sub-heading using an <h3>. It’s simple but restrictive, as you have to ensure the heading levels are appropriate for the intended structure, and you’re limited to six levels. The latter restriction is usually not such a problem, but it still exists for all you heading fanatics (oh you guys!).
HTML5 does this as well. The above example would produce the same outline, but it can be taken even further using the new sectioning elements.
Sectioning elements #
Warning! The HTML5 document outline, in practical terms, is theoretical only, as it has not been implemented in user agents, so people who make use of heading semantics get the heading level as per the h1-h6 elements (HTML 4 outline) i.e. sectioning level is ignored.
<section>, <article>, <aside> and <nav> can all help to create a more logical structure in the document outline. Let’s go crazy and rewrite our previous example using only <h1> elements for headings:
<h1>My fantastic site</h1>
<h1>About me</h1>
<p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
<h1>What I do for a living</h1>
<p>I sell enterprise-managed ant farms.</p>
<h1>Contact</h1>
<p>Shout my name and I will come to you.</p>
- My fantastic site
- About me
- What I do for a living
- Contact
<section> is most appropriate:
<h1>My fantastic site</h1>
<section>
<h1>About me</h1>
<p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
<section>
<h1>What I do for a living</h1>
<p>I sell enterprise-managed ant farms.</p>
</section>
</section>
<section>
<h1>Contact</h1>
<p>Shout my name and I will come to you.</p>
</section>
- My fantastic site
- About me
- What I do for a living
- Contact
- About me
<h2>HTML5 Doctor articles</h2>
<article>
<h1>The section element</h1>
<p>We doctors are a bunch of chums using HTML5 and writing about how we do it...</p>
</article>
<article>
<h1>The article element</h1>
<p>We’ve discussed a lot of new elements here at HTML5Doctor...</p>
</article>
<h1>s, this produces the following outline:
- HTML5 Doctor articles
- The section element
- The article element
<h1>HTML5 Doctor articles</h1>
<article>
<h3>The section element</h3>
</article>
<article>
<h3>The article element</h3>
</article>
<h2>HTML5 Doctor articles</h2>
<article>
<h2>The section element</h2>
</article>
<article>
<h2>The article element</h2>
</article>
<h6>HTML5 Doctor articles</h6>
<article>
<h1>The section element</h1>
</article>
<article>
<h1>The article element</h1>
</article>
Sections may contain headings of any rank, and authors are strongly encouraged to use headings of the appropriate rank for the section’s nesting level.
Note: due to the lack of support in browsers for the document outline and negative prognosis for future support, strengthening of the current advice to a normative requirement is currently under discussion (January 2014).
You should also make sure you’re aware of how differently ranked headings work when used as direct children of a sectioning element. It’s how it worked prior to HTML5:The first element of heading content in an element of sectioning content represents the heading for that section. Subsequent headings of equal or higher rank start new (implied) sections, headings of lower rank start implied subsections that are part of the previous one. In both cases, the element represents the heading of the implied section.
Untitled sections #
Sectioning elements that do not contain a child heading will be labelled as “Untitled”, indicating the lack of a logical heading but preserving the outline as in the example below:<aside>
<section>
<h2>Twitter</h2>
</section>
<section>
<h2>Recent comments</h2>
</section>
</aside>
- Untitled
aside- Recent comments
<aside> and <nav>, as shown below. If you don’t want these headings to be visible, you can always hide them with CSS.
<aside>
<h1>What you're saying</h1>
<section>
<h2>Twitter</h2>
</section>
<section>
<h2>Recent comments</h2>
</section>
</aside>
<section> should not be used arbitrarily. See our section article for more.
How does <hgroup> affect the outline?
<hgroup> affect the outline?<hgroup> is obsolete #
Refer to How to mark up subheadings, subtitles, alternative titles and taglines
<hgroup> article, <hgroup> is all about the document outline. The outliner will disregard all headings within
<hgroup> except the one with the highest ranking. For example, if an <hgroup> contains an <h2>, an <h3> and an <h4>, only the <h2>’s text will be used as the section title in the outline.
<hgroup>’s future is a little uncertain. It was recently removed and then returned to the HTML5 spec, and there are proposals for its removal or replacement with an alternative. We’ll be sure to keep HTML5 Doctor up-to-date with any changes as they unfold.Sectioning roots #
Sectioning roots, introduced in HTML5, isolate certain parts of a document to their own separate outlines. Headings within these elements will not show up in the main outline, where the sectioning root element is the<body>.
The other sectioning root elements are <blockquote>, <figure>, <details>, <fieldset>, and <td>. Each one of these elements is a descendant of the <body> element, but its headings are removed from the top-level outline, instead starting its own isolated outline.
<h1>Top of the outline</h1>
<section>
<h2>A heading in the outline</h2>
<p>Lorem ipsum dolor sit amet...</p>
</section>
<section>
<h2>Another heading in the outline</h2>
<p>Lorem ipsum dolor sit amet...</p>
<blockquote>
<h1>This quoted heading will not appear in the outline</h1>
<p>Lorem ipsum dolor sit amet...</p>
</blockquote>
</section>
<blockquote>’s heading, which has been isolated:
- Top of the outline
- A heading in the outline
- Another heading in the outline
Outlines in the real world #
Unfortunately, there is little support for the new outlining algorithms right now. Search engines may be experimenting with it in their crawling algorithms as you read this, but as far as we know, headings are treated just as they were before. You won’t be penalised for using them, even if you use multiple<h1>s (which have always been okay as far as the spec is concerned). Check out our HTML5 and Search Engine Optimisation article for more on search engines and HTML5.
At the time of writing, browsers and screen readers do not support these new outlines, so if you do use multiple <h1>s in your documents, it may confuse your users. It’s best if you use logical heading levels — <h1>–<h6> — at least until the new outlines are more widely supported.
As for browsers, both recent releases of Firefox and Chrome have a user agent styles that support HTML5 document outlines. Try this bare-bones example in the latest Chrome or Firefox.
Update 21/01/2014
There is still no implementation of the document outline semantics in browsers apart from CSS styling. Refer to this recent article about The HTML5 Document Outline.Final thoughts #
Despite the spotty support, it’s definitely worth thinking carefully about your document outlines so you’re prepared for the future, and tune in here for news of improved support. Get to grips with the sectioning elements and sectioning roots and how each affects the outline. When marking up a new site, consider how you could take advantage of the new document outline algorithm. As user agent support strengthens, pages you made with your new-found knowledge of document outlines will be more accessible. Let us know what you think in the comments below!Outliner tools #
In order to test your outlines, you’ll need an outliner. Here are a few options to get you started:- h5o, a Javascript implementation of the outliner, available as a bookmarklet, extension, or minified JavaScript file
- An Opera extension
- An online outliner where you can upload a file or submit a URL or HTML source to parse (may no longer be under development)
Document Outlines originally appeared on HTML5 Doctor on July 12, 2011.