Is a concept that lives in the HTML specification, but is essentially a fiction in the real world. It is a fiction because user agents have not implemented it and there is no indication that any will.
The HTML5 Document Outline is a dangerous fiction
It is dangerous because it can lead unsuspecting developers to think that using the nesting of heading elements in sectioning elements actually has some effect for users who consume heading semantics. Overwhelmingly the opposite is true. For example If you code a heading as a h1 element and nest it 5 deep in sectioning elements, the document outline leads us to believe that the heading will be a h6, back in the real world the heading is a h1.
<!-- theoretical HTML5 document outline --> <!DOCTYPE html> ... <body> <h1>heading text</h1> <section><h1><h2>heading text... <section><h1><h3>heading text... <section><h1><h4>heading text... <section><h1><h5>heading text... <section><h1><h6>heading text... </section> </section> </section> </section> </section> </body> <!-- What users get --> <body> <h1>heading text</h1> <section><h1>heading text <section><h1>heading text <section><h1>heading text <section><h1>heading text <section><h1>heading text... <!-- DO THIS IF YOU WANT USERS TO GET A MEANINGFUL OUTLINE --> <body> <h1>heading text</h1> <section><h2>heading text... <section><h3>heading text... <section><h4>heading text... <section><h5>heading text... <section><h6>heading text...
Practical advice
If you as a developer want to provide a meaningful document structure, use the h1–h6 elements to express document structure. DO NOT rely upon the HTML5 document outline. By all means use the HTML5 section elements, but do not rely upon them to convey a meaningful structure. If at some point in the future the HTML5 document outline ceases to be a fiction, you will be covered as the use of h1-h6 is backwards compatible.
The advice in the HTML specification is clear on this:
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.
There is now (16/04/14) a warning in section 4.3.10.1 Creating an outline of the HTML spec
There are currently no known implementations of the outline algorithm in graphical browsers or assistive technology user agents, although the algorithm is implemented in other software such as conformance checkers. Therefore the outline algorithm cannot be relied upon to convey document structure to users. Authors are advised to use heading rank (
h1–h6) to convey document structure.
If you don’t think it is clear enough, please file a bug.
Further reading
- Using h1-h6 to identify headings
- HTML5 document outline revisited
- Related bugs:
- modify required heading mappings to reflect reality – HTML spec bug
- expose (heading) level in acc layer based on heading elements outline depth – chrome bug
- expose heading level in acc layer based on outline depth not heading numeric value – Firefox bug
- AX: expose (heading) level based on heading elements outline depth – Webkit bug
- expose output of html5 outline algorithm as a DOM method – IE bug
Comments
Hasn’t this unicorn already bolted given the amount of books, tutorials and talks that have been teaching this for years?
Is backwards compatibilty the reason user agents can’t/won’t implement this?
hi Pete_b,
So now we have lots of tutorials and books re-iterating a fiction, unfortunately restating a fiction does not make it non fiction, implementations do that.
Backwards compatibility is not the reason why it hasn’t been implemented as the algorithm is backwards compatible (if used with correctly ranked heading elements).
Hi Steve, we met at paris web… What about syndication ? Normally the spec says that it is a good practice to have inside sectionning éléments, in particular un articles,in case of sharing / syndication…if you use a h1 then ?
Hi Michel, a few things:
Could you be a little more specific about where exactly “back in the real world the heading is a h1”?
Is it:
– for visual rendering in browsers;
– for logical hierarchy as listed in assistive technologies;
– both.
Thanks.
Hi Nicolas,
The default CSS based font size of headings is effected by nesting (refer to 10.2 The CSS user agent style sheet and presentational hints), but CSS styles are not a robust semantic indicator, and can and are modified by author styles.
Thanks for the quick answer!
I know CSS styles are not enough, but I created a stylesheet a while ago when browsers didn’t apply nesting to their default styles, that’s why I asked… 😉
I added a disclaimer in the begining of the README to link to this article:
https://github.com/nhoizey/HTML5-Titles-Inception
By the way, I also gave a talk in Paris Web, on the subject of “em” based elastic and responsive web design, I’m sad we didn’t meet IRL.
Sorry I missed it and yes it would have been good to meet in person, I am only just across the water, maybe next time.
Yes, next time I’ll try to catch you! 😉
Is this not a question of whether you are looking primarily forward to the future or at the present/past? Interestingly, the WHATWG HTML Living Standard says:
The WHATWG has struck me as relentlessly pursuing the future in a way the W3C can’t / doesn’t. I don’t want to categorize it as a “skating to where the puck is going, not where the puck is” situation, because WHATWG make it clear that they also think the pre-
sectionnesting is acceptable, but, at the same time, folks were using “fictional” XHTML (fictional because Internet Explorer, the most popular browser at the time, didn’t support XHTML with the correct MIME Type until IE9). The HTML5 outline is “fictional” for the same reason. It may lack support in important user agents, but it is something that can be parsed and understood on an intellectual level.Or, I guess, a better question: Who does it actually hurt in practice to use nested
sections instead of ranked headings? If you have any examples (especially if you’ve already written about it), I’d love to hear them. I’ve done a little experimenting with screen readers, for example, and I know they will behave differently not understanding the HTML5 outline. I just don’t know from actual users’ perspectives if that is a major usability issue in practice (especially versus incorrectly nested headings).Hi Robert,
The W3C HTML spec pursues the future; the spec includes the outline algorithm, what it no longer does (unlike the whatwg spec), is mislead developers into thinking that because the outline algorithm is in the spec it actually does something .
As a developer I want to know how to code stuff that actually benefits users, not what can be and would like the HTML spec to acknowledge that developers are a core audience of the HTML spec, by not leading us into fairyland. As co-editor of the HTML spec that is what I have been attempting to do; improve author advice and requirements to help developers code in a way which takes into account practical realities that effect real users. There is still a long way to go on this front…
From the most recent Screen Reader User Survey, users were asked the question:
47% found them to be very useful.
Thanks for the feedback, Steve.
For what it’s worth, I’m not accusing the W3C of not pursing the future; rather, I was insinuating that the WHATWG seems to not be interested in anything except the future, at least in my impression, because:
1. They feel like they have addressed the past (when it was still the present during the early WHATWG days) as they made (make?) efforts to reverse engineer documentation for existing browser behaviors.
2. They addressed the present yesterday when it was still the future.
That was my take away from the idea of a living HTML standard, which is why I was asking about philosophical differences. I didn’t mean to ruffle any feathers if I did!
if html5 is like fiction..then what version of html do you recommend ?
Hi Nicole, I did not say “html5 is like fiction” I said the outline algorithm is a fiction as it is not implemented. When new features are added to the HTML spec, they are generally a fiction, but there is an expectation that they will be implemented in due course, the outline algorithm has been in the HTML spec for around 5 years…
Hi Robert,
The interesting thing about the whatwg is that many of same people also participate in various working groups at the W3C and the browser vendors involved are the same (except for the absence of Microsoft in the whatwg). The influence of the whatwg on the w3c has been mostly positive in moving W3C processes and standards development into the 21st century (see recent discussion on this list as an example), but I don’t think it is a model that the W3C could/should embrace wholesale as it is overly browser centric (I think). In regards to the continuing HTML development at the W3C you may be interested in reading the fairly recent HTML5 Doctor interviews with Robin Berjon and myself.
To illustrate the browser behavior at this moment, I made 3 testpages: the good, the bad and the ugly. 😉
With all H1 headers in nested sections (and default H1 font-size): html5-document-outline-1.htm (the bad)
With H1, H2, H3 … headers in nested sections (& default font-sizes): html5-document-outline-2.htm (the good)
With all H1 headers in nested sections (& specified H1 font-size): html5-document-outline-3.htm (the ugly)
Thanks Francky!
It looks like JAWS does correctly follow the outline – an h1 in a section will be reported as an h2.
However – Gez Lemon noted that if you don’t rely on HTML5 sectioning when selecting headings (to stay compatible with other screen readers), you need to add “aria-level” to each of them – otherwise JAWS will read them out one level lower than they should be.
The HTML5 outline algorithm and JAWS
Screen reader support for HTML5 sections
Hi Chris, the outline algorithm or a borked subset of it was implemented in JAWS, it got removed in JAWS 15
Bummer. Still, seems like it might be a good idea to include “aria-level” since a fair amount of JAWS users are/will still be on versions 12-14.
Why do you suppose UA’s are so reluctant to implement HTML5 outlining? Waiting for the spec to stabilize? Just not interested?
Hi Steve,
Thanks for pointing me out to this page on Bugzilla. Exactly what I needed, because it seems I was too forward with implementing HTML5, using al H1 element throughout the page, but with a correct ‘outline’ (see
caesarsbeauty.nl).My question: how do you (or I) check if user-agents already have accepted new HTML guidelines, in your comments I read the ‘outline’ principle is already around for 5 years. And in what way should a normal browser implement this? I can only think this is helpfull for screenreaders for people without sight, to easily discover the site structure. Forgive me if this is a strange question, but I don’t know much about user agents. To put it differently, using the old method with h1-h6 headings, which I assume is implemented in user agents, is a nice way for people without sight using screenreaders to go through the content, but when I use a normal browser, what benefit I have from a website that is doing this the right way? What is ‘see’ defines how easily I can go through the content right, not the structure behind it.
To be honest, I always tried to implement h1-h6 the right way, but I did this for the search engines, who are relying on the structure, so they could define what is important or not.
So in this question, it seems important to me that search engine crawlers and screenreaders can understand the ‘outline’, but I don’t know why it is important for normal browsers. And do search engines already understand the ‘outline’ principle?
Kind regards,
Willem
PS On https://www.w3.org/TR/WCAG20-GENERAL/H42.html the link to “Quick tips for accessible headings” is dead.
In your reply to this comment in the previous article, you suggest that the document outline is still valuable as a means of verifying if the combination of headings + section elements makes sense semantically. Can you clarify its usefulness in that situation versus your advice here which suggests that the HTML5 it isn’t actually of any practical value for today’s developers? This blog is a terrific resource, but I’m genuinely confused after reading these two articles back to back!
Hi Francky,
Thanks, but I don’t fully understand the principles yet I guess. In this scenario https://clba.nl/sitepoint/html5-document-outline-2.htm the second H1 is smaller then normal, but what does this mean, does it harm, or not? Or is it just to illustrate that browsers does not handle the sections correct at this time? What if we leave the sections out completely, does it give a good size for the second h1?
Kind regards,
Willem
Thanks for the article. I’ve got questions, but I’ll just do one for now.
Say I’ve got my main content, like a blog post, and I’ve also got a set of 3 features that I want to be portable, that get tacked on the bottom of the blog post at random. These are features that can go anywhere on the site. How do I mark up the features? Do I use an H1 for the title, or arbitrarily assign it another heading level?
also, should I completely ignore this page then?: https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Sections_and_Outlines_of_an_HTML5_document
Hi Jake, see note I added
Hi Jake, If you want the document to have a meaningful document outline for users, you will need to modify the heading level based on its nesting level in the page its being used.