Updated 21/01/2014 by Dr. Steve

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 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> This example would produce the following outline: My fantastic site About me What I do for a living Contact <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. Creating document outlines prior to HTML5 was simple. You had six heading elements,through. Lower-numbered headings were of a higher rank of higher-numbered ones — i.e.was ranked higher thanThis example would produce the following outline:titles are children of the, and the “About me” content has a further sub-heading using an. 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. The concepts behind HTML5 document outlines are actually older than you might think! Tim Berners-Lee posted to the www-talk mailing list <article> , <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> The outline would now look like this: 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> Run it through the outliner and we’re back to normal: My fantastic site About me What I do for a living Contact <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> Even though the articles contain <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> When choosing which heading to use in your documents, 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. — HTML 5.1 specification The concepts behind HTML5 document outlines are actually older than you might think! Tim Berners-Lee posted to the www-talk mailing list back in 1991 (props to Dr Oli for digging that up), suggesting something quite close to what is demonstrated in this article. The sectioning elements <section> <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 onlyelements for headings:The outline would now look like this:is most appropriate:Run it through the outliner and we’re back to normal:Even though the articles contains, this produces the following outline:When choosing which heading to use in your documents, the spec has recommendations: 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. — HTML 5.1 specification 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> Running this through the outliner produces this outline: Untitled aside Twitter 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> Remember, elements like <section> should not be used arbitrarily. See our 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:Running this through the outliner produces this outline:and, as shown below. If you don’t want these headings to be visible, you can always hide them with CSS.Remember, elements likeshould not be used arbitrarily. See our section article for more. 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:

How does <hgroup> affect the outline? <hgroup> is obsolete # Refer to How to mark up subheadings, subtitles, alternative titles and taglines As Dr Richard Clark said in our <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. At the time of writing, <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> This results in the following outline. Notice that it lacks the <blockquote> ’s heading, which has been isolated: Top of the outline A heading in the outline Another heading in the outline 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. The other sectioning root elements are, and. Each one of these elements is a descendant of theelement, but its headings are removed from the top-level outline, instead starting its own isolated outline.This results in the following outline. Notice that it lacks the’s heading, which has been isolated:

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 <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 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 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 multiples in your documents, it may confuse your users. It’s best if you use logical heading levels —— 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.There isapart 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) In order to test your outlines, you’ll need an outliner. Here are a few options to get you started: 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!

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.