# Document Outlines

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

1. My fantastic site
1. What I do for a living
2. Contact


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

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

1. My fantastic site
3. What I do for a living
4. Contact


Clearly, that’s no good — we’ve lost our structure! With sectioning elements, we can make it look like before without changing those headings. In this particular example, I think <section> is most appropriate:

<h1>My fantastic site</h1>
<section>
<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:

1. My fantastic site