Last Updated: February 25, 2016
· ash

Check your HTML document outline

Understanding exactly where and when to use the elements introduced in HTML5 can be tricky to begin with. I at first slapped them all over the place with little caution.

"This is semantic, right?"

I read a fair few articles on how to use the veritable smorgasbord of shiny new HTML5 elements sensibly - but I was never sure I had understood completely.

"This is a section of the page with an article in it, I guess each column inside is a section of that article and that article's image is a section of the article, too, so best pop it in a section. Oh yeah, and the whole thing is a child of a main page section."

Wrong. Page layout markup can get pretty damn complicated. It's unfortunate, but in order to create even the most mundane designs, it's often necessary to resort to a little extraneous markup and dubious element nesting. Yeah, it's possible to cut out a lot of the soup with some cleverly used :befores and :afters, but this won't take care of everything. If you're brandishing HTML5's 'semantic' elements in the same unwieldy fashion that I initially did, you're really just hitting your site with a big ol' stick of muddlement.

This changed when I ran my markup through a tool to analyse the document outline. I use a handy Chrome extension to make this easy to do throughout the dev process ( Just checking out the document outline of a site I'd recently built helped me to understand the whole concept a lot better than any of the articles I'd read previously.

If you haven't before, I really recommend making sure that the markup you are writing is actually adhering to the structure of the content you are marking up. The Chrome HTML5 document outline extension is now used (somewhat) constantly throughout my frontend dev process. Go check out your document outlines now!

(Disclaimer: 'document outline' is not an HTML5 thing, but I can't imagine many people who care about such things haven't started using 'HTMl5' yet. There is more comprehensive documentation of the document outline created in both HTML4 and HTML5 available on MDN:

7 Responses
Add your response

Great tip man!

over 1 year ago ·

Or you can use it anywhere you want with this little bookmarklet :

over 1 year ago ·

Funnily, the outline for pro tips here on coderwall is little weird :)
Hopefully, your tip will get many votes and deserve the devs' attention :)

over 1 year ago ·

does MAIN not now need to be included in the list of section elements?


over 1 year ago ·

@jmp909 Do you have any references describing the affect of <main> on the document outline? I did a quick Google but couldn't find any info.

over 1 year ago ·

sorry i appear to have been mistaken:

"Because <main> isn’t sectioning content, it doesn’t affect the document outline in the same way article, nav, or section do."

over 1 year ago ·

@jmp909 Cool, thanks for the info 😊

over 1 year ago ·