Avoiding common HTML5 mistakes

by .

Between curating sites for the HTML5 gallery and answering readers’ questions here at HTML5 Doctor, I see a host of HTML5 sites and their underlying markup. In this post, I’ll show you some of the mistakes and poor markup practices I often see and explain how to avoid them.

Don’t use section as a wrapper for styling

One of the most common problems I see in people’s markup is the arbitrary replacement of <div>s with HTML5 sectioning elements — specifically, replacing wrapper <div>s (used for styling) with <section>s. In XHTML or HTML4, I would see something like this:

<!-- HTML 4-style code -->
<div id="wrapper">
  <div id="header">  
    <h1>My super duper page</h1>
    <!-- Header content -->
  </div>
  <div id="main">
    <!-- Page content -->
  </div>
  <div id="secondary">
    <!-- Secondary content -->
  </div>
  <div id="footer">
    <!-- Footer content -->
  </div>
</div>

Now, I’m instead seeing this:

<!-- Don’t copy this code! It’s wrong! -->
<section id="wrapper">
  <header>  
    <h1>My super duper page</h1>
    <!-- Header content -->
  </header>
  <section id="main">
    <!-- Page content -->
  </section>
  <section id="secondary">
    <!-- Secondary content -->
  </section>
  <footer>
    <!-- Footer content -->
  </footer>
</section>

Frankly, that’s just wrong: <section> is not a wrapper. The <section> element denotes a semantic section of your content to help construct a document outline. It should contain a heading. If you’re looking for a page wrapper element (for any flavour of HTML or XHTML), consider applying styles directly to the <body> element as described by Kroc Camen. If you still need an additional element for styling, use a <div>. As Dr Mike explains, div isn’t dead, and if there’s nothing else more appropriate, it’s probably where you really want to apply your CSS.

With that in mind, here’s the correct way to mark up the above example using HTML5 and a couple of ARIA roles. (Note: you may need one <div> depending on your design.)

<body>
  <header>  
    <h1>My super duper page</h1>
    <!-- Header content -->
  </header>
  <div role="main">
    <!-- Page content -->
  </div>
  <aside role="complementary">
    <!-- Secondary content -->
  </aside>
  <footer>
    <!-- Footer content -->
  </footer>
</body>

If you’re not quite sure which element to use, then I suggest you refer to our HTML5 sectioning content element flowchart to guide you along your way.

Only use header and hgroup when they’re required

the <hgroup> has now been removed from the HTML5 specification, please keep that in mind when reading the rest of this article.

There’s no sense writing markup when you don’t have to, right? Unfortunately, I often see <header> and <hgroup> being used when there’s no need for them. You can get up to speed with our articles on the <header> element and the <hgroup> element, but I’ll briefly summarise:

  • The <header> element represents a group of introductory or navigational aids and usually contains the section’s heading
  • The <hgroup> element groups a set of <h1><h6> elements representing a section’s heading when the heading has multiple levels, such as subheadings, alternative titles, or taglines

Overuse of header

As I’m sure you’re aware, the <header> element can be used multiple times in a document, which has popularized the following pattern:

<!-- Don’t copy this code! No need for header here -->
<article>
  <header>  
    <h1>My best blog post</h1>
  </header>
  <!-- Article content -->
</article>

If your <header> element only contains a single heading element, leave out the <header>. The <article> ensures that the heading will be shown in the document outline, and because the <header> doesn’t contain multiple elements (as the definition describes), why write code when you don’t need to? Simply use this:

<article>  
  <h1>My best blog post</h1>
  <!-- Article content -->
</article>

Incorrect use of <hgroup>

On the subject of headers, I also frequently see incorrect uses of <hgroup>. You should not use <hgroup> in conjunction with <header> when:

  • there’s only one child heading, or
  • the <hgroup> would work fine on its own (i.e., without the <header>).

The first problem looks like this:

<!-- Don’t copy this code! No need for hgroup here -->
<header>
  <hgroup>  
    <h1>My best blog post</h1>
  </hgroup>
  <p>by Rich Clark</p>
</header>

In that case, simply remove the <hgroup> and let the heading run free.

<header>
  <h1>My best blog post</h1>
  <p>by Rich Clark</p>
</header>

The second problem is another case of including elements when they’re not necessarily required.

<!-- Don’t copy this code! No need for header here -->
<header>
  <hgroup>  
    <h1>My company</h1>
    <h2>Established 1893</h2>
  </hgroup>
</header>

When the only child of the <header> is the <hgroup>, why include the <header>? If you don’t have additional elements within the <header> (i.e., siblings of the <hgroup>), simply remove the <header> altogether.

<hgroup>  
  <h1>My company</h1>
  <h2>Established 1893</h2>
</hgroup>

For more <hgroup> examples and explanations, read the detailed article about it in the archives.

Common mistakes with the figure element

Ah, <figure>. The appropriate use of this element, along with its partner-in-crime <figcaption>, is quite difficult to master. Let’s look at a few common problems I see with <figure>.

Not every image is a figure

Earlier, I told you not to write extra code when it’s not necessary. This mistake is similar. I’ve seen sites where every image has been marked up as a <figure>. There’s no need to add extra markup around your images for the sake of it. You’re just creating more work for yourself and not describing your content any more clearly.

The spec describes <figure> as being some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document. Therein lies the beauty of <figure>, that it can be moved away from the primary content — to a sidebar, say — without affecting the document’s flow.

If it’s a purely presentational image and not referenced elsewhere in the document, then it’s definitely not a <figure>. Other use cases vary, but as a start, ask yourself, Is this image required to understand the current context? If not, it’s probably not a <figure> (an <aside>, perhaps). If so, ask yourself, Could I move this to an appendix? If the answer to both questions is ‘yes’, it’s probably a <figure>.

Your logo is not a figure

Segueing nicely on, the same applies to your logo. Here are a couple of snippets that I see regularly:

<!-- Don’t copy this code! It’s wrong! -->
<header>
  <h1>
    <figure>
      <img src="/img/mylogo.png" alt="My company" class="hide" />
    </figure>
    My company name
  </h1>
</header>
<!-- Don’t copy this code! It’s wrong! -->
<header>  
  <figure>
    <img src="/img/mylogo.png" alt="My company" />
  </figure>
</header>

There’s nothing else to say here. It’s just plain wrong. We could argue until the cows come home about whether your logo should be in an <h1>, but that’s not what we’re here for. The real issue is the abuse of the <figure> element. <figure> should be used only when referenced in a document or surrounding sectioning element. I think it’s fair to say that your logo is rarely going to be referenced in such a way. Quite simply, don’t do it. All you need is this:

<header>  
  <h1>My company name</h1>
  <!-- More stuff in here -->
</header>

Figure can be more than an image

Another common misconception regarding <figure> is that it can only be used for images. This isn’t the case. A <figure> could be video, audio, a chart (in SVG, for example), a quote, a table, a block of code, a piece of prose, or any combination of these and much more besides. Don’t limit your <figure>s to images. Our job as web standards affectionadoes is to accurately describe the content with our markup.

A while back, I wrote about <figure> in more depth. It’s worth a read if you want more detail or need a refresher.

Don’t include unnecessary type attributes

This is probably the most common problem we see in HTML5 Gallery submissions. While it isn’t really a mistake, I believe it’s best practice to avoid this pattern.

In HTML5, there’s no need to include the type attribute on <script> and <style> elements. While these can be a pain to remove if they’re automatically added by your CMS, there’s really no reason to include them if you’re coding by hand or if you have tight control over your templates. Since all browsers expect scripts to be JavaScript and styles to be CSS, you don’t need this:

<!-- Don’t copy this code! It’s attribute overload! -->
<link type="text/css" rel="stylesheet" href="css/styles.css" />
<script type="text/javascript" src="js/scripts.js"></script>

Instead, you can simply write:

<link rel="stylesheet" href="css/styles.css" />
<script src="js/scripts.js"></script>

You can also reduce the amount of code you write to specify your character set, amongst other things. Mark Pilgrim’s chapter on semantics in Dive into HTML5 explains all.

Incorrect use of form attributes

You may be aware that HTML5 has introduced a range of new attributes for forms. We’ll cover them in more detail in the coming months, but in the meantime, I’ll quickly show you a few things not to do.

Boolean attributes

Several of the new form attributes are boolean, meaning their mere presence in the markup ensures the behaviour is set. These attributes include:

  • autofocus
  • autocomplete
  • required

Admittedly, I only rarely see this, but using required as an example, I’ve seen the following:

<!-- Don’t copy this code! It’s wrong! -->
<input type="email" name="email" required="true" />
<!-- Another bad example -->
<input type="email" name="email" required="1" />

Ultimately, this causes no harm. The client’s HTML parser sees the required attribute in the markup, so its function will still be applied. But what if you flip the code on its head and type required="false"?

<!-- Don’t copy this code! It’s wrong! -->
<input type="email" name="email" required="false" />

The parser will still see the required attribute and implement the behaviour even though you tried to tell it not to. Certainly not what you wanted.

There are three valid ways for a boolean attribute to be applied. (The second and third options only apply if you’re writing XHTML syntax.)

  • required
  • required=""
  • required="required"

Applying that to our above example, we would write this (in HTML):

<input type="email" name="email" required />

Summary

It would be impossible for me to list here all the quirky markup patterns and practices I’ve come across, but these are some of the most frequently seen. What other common markup mistakes have you spotted around the web? Which areas of HTML5 require further clarification? We’d love to help get the wording or examples in the spec changed to make them a little more specific, so leave your thoughts below, and don’t forget to escape your HTML!

Thanks to Ian Devlin, Derek Johnson, Tady Walsh, the HTML5 Gallery curators, and the HTML5 Doctors for their input to this article.

106 Responses on the article “Avoiding common HTML5 mistakes”

  • Jono says:

    Brilliant article thanks Rich. tag finally I get it!

  • Ric says:

    In the first example why is it and not an article?

  • gnur says:

    Wouldn’t
    <input type=”email” name=”email” required>
    be just as valid as with the extra ‘/’?
    Because html5 is not xhtml, there is no explicit need to (self-)close tags right?

  • Ryah says:

    “Earlier, I told you not to write extra code when it’s not necessary”

    That’s bad journalism right there. TELLING people what to do because you assume everyone is dumber than you is a sure-fire way to look like an arrogant prick.

    I don’t get it with you HTML5 f*cktards. You are just rearranging a few new elements with a big, smug grin on your faces. It’s not exactly brain surgery is it.

  • Ric says:

    If figures can be used for quotes then, would the figcaption be used for the person / reference of the quote?

    Would this have been a good example for http://html5doctor.com/blockquote-q-cite/ It seems a bit better than including footers etc in the blockquote. I just find it strange including something that isn’t actually the quote, in the quote.

  • Gareth says:

    Interesting article Rich and one that kind of emphasises my fear of creating HTML5 related sites.

    With the spec so actively changing and a real in-depth knowledge needed to use any of the new semantic elements – it’s no wonder it makes me, and probably others, incredibly nervous about kick starting HTML5 development :(

    It’s so frustrating to see so many ‘HTML5’ sites out there that are blatantly using the semantic structure incorrectly!

  • Thiago Dini says:

    “<script href=”js/scripts” /></script>” is correct? Or <script src=”js/scripts.js” /></script> is better?

  • Wayne says:

    Just a quick point about the required attribute, if you use the attribute with no value then IE & below won’t recognise it. (ie, you must use at least required=””)

    It’s a shame, because I really like that you can just drop these boolean attributes into an element and they’re true because they’re there.

    @trolleymusic

  • fjpoblam says:

    Okay, Richard. I take your points, and have been using many of your described habits for awhile. But the more often I read HTML5doctor, the more I am persuaded that it is virtually impossible to write the “perfect” HTML5 website conforming to *all* the recommendations at HTML5doctor versus *all* the recommendations at WHATWG versus the rules so far described at W3.

    I will admit, of course, that all these recommendations are matters of *subjective* human interpretation. Yet, HTML5doctor becomes a bit prudish and pedantic at times. The recommendations do *not* always yield code that is more easily maintained, more user-friendly, and more bandwidth friendly!

  • Alvin Crespo says:

    Seems that the hgroup tag is still being considered for removal:
    http://www.whatwg.org/specs/web-apps/current-work/#the-hgroup-element

  • Brajeshwar says:

    @Wayne

    In IE, would it not just ignore it as it won’t understand that attribute. I’d rely on something like Modernizr at that stage to use an alternative method, with JS for the function and a CSS styling for the visual part of it.

  • Joel says:

    Why exactly do you consider pagination and tertiary navigation not worthy of a <nav> element? Surely they are, by definition, navigation and in the case of pagination, sometimes a very important piece of navigation.

  • alexander farkas says:

    Here is a common mistake made by html5doctor.com. http://jsfiddle.net/trixta/ZMsm7/

  • fjpoblam says:

    Notify your HTML5 stylist to check cross-browser/platform rendering on MacOSX 10.6.8, Chrome 12.0.742.122

  • Bruce Lawson says:

    Joel asks “Why exactly do you consider pagination and tertiary navigation not worthy of a

  • Thiago Dini asked:

    “<script href=”js/scripts” /></script>” is correct? Or <script src=”js/scripts.js” /></script> is better?

    None of them. This is correct:

    <script src="js/scripts"></script>

  • Thiago Dini says:

    Exactly, don’t have close self.

  • Christian Romney says:

    RE: self-closing tags, those aren’t the only typos (link/input)…

  • Also: don’t blindly use <aside> for everything that happens to be in a sidebar as per your current design.

  • Sergey says:

    100% with Ryah and fjpoblam!

  • guimihanui says:

    There are three valid ways for a boolean attribute to be applied. (The second and third options only apply if you’re writing XHTML.)

    required
    required=""
    required="required"

    It is wrong that The second and third options only apply if you’re writing XHTML. The second and third options are valid even in HTML. See http://www.w3.org/TR/html5/common-microsyntaxes.html#boolean-attributes

  • @guimihanui: I think Rich meant to write “The second and third options only apply if you’re writing XHTML syntax.”

  • Thanks to all for your feedback, some specific responses below:

    @gnur – you’re right you don’t need the trailing slash but can include it if you prefer to write your markup using XHTML syntax.

    @Ric – that’s certainly an option but the context is important. Pullquotes for example wouldn’t be marked up in a figure. Will have a think about that one some more and update the appropriate articles.

    @Thiago – Yes that was a typo in the article, it’s now been updated.

    @Wayne – Thanks for the tip. Are you referring to IE10? Versions below 10 have no support for HTML5 forms.

    @fjpoblam – Interpretation of web standards is nothing new and we will always disagree in some cases. How long did it take us to decide that an unordered list should be used to markup navigation for example? What’s the styling issue you’re seeing? We’ve got the same setup and it’s ok for us.

    @Alvin – yes, we wrote an article about that recently. The hgroup hokey cokey

    @Joel – It depends on what type of pagination I guess. If we’re talking about Google search results then a nav probably is appropriate. If we’re talking about an article spanning multiple pages to increase ad impressions, not for me. However, as you can see Bruce see’s it from a different angle.

    @Christian – I’ve fixed a few typo’s, are there any I’ve not got?

    @Mathias – yes good point, thanks for bringing it up. You’re right re ‘syntax’ added that in now!

  • @Ryah – I thought about not gracing your comment with a response but changed my mind so here goes.

    Thankfully, I’m not a journalist. I make websites for a living so no worries there.

    I certainly don’t think that everyone is dumber than I am, in fact very much the opposite. A high percentage of our readers pick up errors in our articles and bugs in our code which is invaluable for a resource such as HTML5 Doctor. That’s the beauty of the web community, that we can share information without people always writing nasty, detrimental comments. If you don’t have anything constructive to say, it’s probably best to say nothing at all without going on an unsolicited rant.

    I don’t know where to start with your last point. I guess if you don’t like HTML5 and the new elements it has introduced to help make the web a more semantic, accessible place then stick to writing HTML4.

  • @Ric — I’ve been thinking about <figure> and <figcaption> for <blockquote> attribution, but there’s one potential problem, the “moved away from that primary content” part. While prints or photos were historically moved to the center of a book, quotations have always been main content. However, I think the common perception of <figure> as a way to just add a caption to an image may render this moot. I also note there’s a poem with citation example in the spec. It’s entirely possible Hixie might agree with you here.

    “I just find it strange including something that isn’t actually the quote, in the quote.” I’m the opposite here. For me this is like saying the header or footer of an <article> should be outside it. However you’re definitely not the only one who feels this way.

    @fjpoblam — “it is virtually impossible to write the ‘perfect’ HTML5 website”. I think you’re approaching this from an XHTML valid/invalid mindset. The HTML5 sectioning elements are very much up to your personal interpretation for example, e.g. the <nav> discussion above. Rather than worrying, just do the best you can safe in the knowledge that browsers will do their best to render your content, validate, and keep learning. We all make mistakes (my <blockquote> article, anyone? :)), but by discussing them we’re learning and finding better ways to do things. This is great, and for example the <blockquote> spec will probably be changed based on the problem our non-conforming usage uncovered.

    @Ryah — “It’s not exactly brain surgery is it” Aah, you appear to be after our other medical blog. I trust the content there will be more to your liking ;)

  • PhiLho says:

    Richard, I think that what gnur meant was either you write:
    (pure HTML)
    or:
    (correct XHTML)
    but not:

    as you wrote: you mix HTML style with XHTML style. It can be correct for HTML, but unnecessary, and it is not correct XHTML (style).

    Good article, anyway. :-)

  • Stomme poes says:

    I don’t see the point in bothering people about adding in type attributes on script and style tags when using examples with XHTML-style closing slashes everywhere (they are just as useless, aren’t they). Except where in the script tags they seem to be closed twice?? I assume that’s a set of typos though.

    The confusion over required=”false” maybe comes from sources where I’ve read about the ARIA version: aria-required by itself was true, but if working with JavaScript then aria-required=”false” or aria-required=”” were supposed to turn it off. Or was it?

  • Stomme poes says:

    …by “script tags closed twice”, I mean
    Instead, you can simply write:

    <script src=”js/scripts.js” /></script>
    The slash after the src.

  • @all — yup <script src="js/scripts.js" /></script> was a typo. Thanks for pointing it out, it’s fixed now. For the great HTML vs XHTML closing slashes/talisman debate, check out Dr Bruce’s article HTML 5 + XML = XHTML 5. For the record, in HTML5:
    <script src=”js/scripts.js”></script>
    =
    <script src=”js/scripts.js” />

  • fjpoblam says:

    FWIW The styling problem I see is in the bottom divs (if divs is what they are – I didn’t View Source). “RELATED POSTS” overlays advice for posting at the point of “You can also use”. My browser preferences are set at font-size 18. A more adept styling would allow for such a preference (at least it does on my websites).

  • fjpoblam says:

    Oh, and, for my other comment, IMHO, the description of using &lti&gt using an inline class versus using an external stylesheet contributes to a form of “classitis” which I like to avoid.

  • Wayne says:

    @Brajeshwar: Agreed, and I do – but if you’re doing a fallback validation, or even just want to get all the required inputs, a $('input[required]') (to use a jquery example) with <input required/> won’t return anything on <= IE8 —

    $('input[required=""]') & <input required=""/> will though.

    @Richard Clark: 8 and below – you can still pick out the elements that have the attribute with 9, even if the attribute has no value associated – and while the browser may have no native support for cool things like validation, having an attribute for required still works from a script point of view.

  • alexander farkas says:

    I really would like to get feedback, about my too short comment above. Mainly, I only shared a link with examples and some explanation. My opinion is, that the following output example is a bad, but common mistake:


    <input type="range" oninput=" $( output ).prop( 'value', value ) " />
    <output id="output">50</output>

    The reason, why I think it is a mistake, has the following reasons. The output element should be implemented as a liveregion, which means everytime, the textcontent changes the changed content is announced by Screenreaders, which is good for a11y, if you are calculating or transforming some input[s], but it is really bad if you simply only repeat the value of an input element. It’s a case of too much accessibility.

  • Oli Studholme wrote:

    For the record, in HTML5:

    <script src="js/scripts.js"></script>
    =
    <script src="js/scripts.js" />

    The second option can only be used in XHTML5 served as “application/xhtml+xml”. If it is used in ordinary HTML5 (served as “text/html”) the second option is equal to <script src="js/scripts.js"> with no closing tag, and that is obviously invalid, and will probably break badly. The slash has no meaning in plain HTML5!

    On a side note: The space before the slash in self-closed elements is not needed anymore. The only browser that ever needed it, Netscape (4 and earlier), is long gone. So, if you like the XHTML5 syntax, you can just do this:

    <input value="whatever"/>
    <img alt="" src="whatever.png"/>
    etc.

  • Stomme poes says:

    @Bertil:

    But is it true that Safari is the one browser who does see <script blah blah /> as valid while all others don’t (some “bug” I remember reading about somewhere)? (and if Safari, maybe also Chrome)

  • developers are still wrong about the use of the HTML5, mainly on issues related to .

    Good tips man

  • Allan says:

    For input required, w3c shows it as required=”required” ? http://www.w3schools.com/html5/att_input_required.asp but you just write “input… required”

    Is there a difference? I would be inclined to go by the w3c, no?

  • PhiLho says:

    Mmm, I should have read the side bar… Inconvenience of not having a preview facility…
    It was:
    <input type=”email” name=”email” required> (HTML)
    <input type=”email” name=”email” required="r"/> (XHTML)
    not
    (half backed…)

    @Allan: don’t mention W3C with a link to W3Schools! That’s heresy… :-) See W3Fools… ;-)

  • @fjpoblam — the rendering bug you see will be addressed when we move to a liquid layout. I have no idea what you mean by your “classitis” comment though.

    @Bertil Wennergren — thanks for the correction. I must have been thinking of <link> or something there.

    @Stomme poes — you’re right. Safari traditionally accepted <script /> due to Dashboard apps. They’ve stopped supporting it now (with Safari 5.1?) as it isn’t compliant with HTML5 (ref: bugs 4071, 10099, 42909).

    @PhiLho — I pity da W3 foo’! [:mrt:]

  • Fwiw, “void elements” (and foreign elements = elements from the MathML namespace and the SVG namespace) can have an optional XHTML-style closing slash:

    • area
    • base
    • br
    • col
    • command
    • embed
    • hr
    • img
    • input
    • keygen
    • link
    • meta
    • param
    • source
    • track
    • wbr

    Regarding the closing slash, “This character has no effect on void elements, but on foreign elements it marks the start tag as self-closing.”

  • First up, thanks for the great article. You’ve got a fantastic resource here for html5 markup.

    One thing I wanted to clarify was the <header> element. I can certainly understand the reasoning behind not including extra markup when you don’t need to, as in your example of leaving out the <header> element if there’s only a single <h1>. Reading through the W3c Spec though, it states:

    A header element is intended to usually contain the section’s heading (an h1–h6 element or an hgroup element)

    Specifically, it says “an h1-h6 element”. Element being singular. So, would it really be that bad if you enclose a single h1 within a header?

  • Ranjeet says:

    very useful article thanks for sharing.

  • Jason says:

    Didn’t you know that HTML 5 isn’t about semantic markup? It was created to give “front-end developers” some specialized knowledge to justify their job titles ;)

  • Hva Faen says:

    How come ‘Pagination controls’ are deemed unworthy of nav tags?
    I know they’re of lesser importance than your main site navigation but all the same they may hold significant weight within their context

  • Rob M says:

    I disagree with leaving off the type attributes for scripts and style sheets. Sure, HTML5 doesn’t need them. But….

    You’re site is still going to be hit by HTML4 browsers and they do need them..

  • You’re [sic] site is still going to be hit by HTML4 browsers and they do need them..

    No they don’t. Small changes like this would have never been accepted in HTML5 if they broke backwards compatibility.

  • “There’s no sense writing markup when you don’t have to, right?”

    I guess that’s a matter of preference (or even a dogmatic difference) that wouldn’t qualify it as a mistake. If you wish to plan for the future or if you consider the html structure of a component to be a generic semantic and structural description that should be able to expand over time and across different sites, then yeah, there is sense in writing mark-up that might be too verbose in one particular example on one particular page of your site.

  • Dave Patrick says:

    Thanks about the advice. I’d always figured that the element had more use than for just images. Tables, video, canvas(?!), etc, etc. Go figure!

  • Alon guo says:

    I have translated this great article into chinese, If you like chinese version you can vist 如何避免 HTML5 的常见误区 Thanks Richard Clark

  • The best article of html5doctor.

    Thanks for sharing!

  • David Millar says:

    Regarding images and image galleries, what would be the most proper way to display a set of images and captions on a page if those images are the primary content? Definitely not <aside> (I’m fairly sure), but I’m having trouble understanding if <figure> and <figcaption> would be the proper tags to use.

    My intended use case is grouping 1-3 pictures within a <figure> and using <figcaption> to label the group as a whole.

    Thanks for the excellent article and thanks in advance for any follow-up/help/advice.

  • Szlabany says:

    Very usefull article. I realize there’re many things to improve when I designing my websites, so thanks for sharing your experience.

  • Daryl says:

    Brilliant and helpful article for an HTML5 beginner, thanks muchly :)

  • gauss says:

    Excellent article.

    Tky

  • Usme Cah says:

    nav bugs me. It should be context-sensitive. If it’s a descendant of an article or a section it’s primary navigation for that context. If it’s a descendant of body (possibly with header or some divs between) it’s primary navigation for the site.

    But that’s not the way the spec reads, so I guess I’ll just have to either get used to doing something that feels weird & wrong…

  • @Usme Cah — while the spec doesn’t state this explicitly in <nav>’s description, your explanation is dead on. Refer to the spec on other sectioning elements like <article>. Also note the spec’s examples for <nav> are both context-sensitive. Yay for being right eh? :)

  • Great article :)
    HTML5 is awesome & these mistakes occur many times unintentionally..

  • Jack Westbrook says:

    What a brilliant article. I’m currently working on a few html5 sites and this was a very enlightening read for me. Cheers.

    Just a note – your link to Mark Pilgrim’s Dive Into HTML5 semantics page points to a 410. I found it eventually at .info rather than .org.
    http://diveintohtml5.info/semantics.html

  • @Jack Westbrook — d’oh! We’re aware of the problem (ahem) but actually updating links seems to have slipped through the cracks… until now! Thanks for the prompt :)

  • dodo dard says:

    Very good article, thanks indeed the new semantic gives a new standard how we define a html. But still confuse who benefits all this new semantic ? Is there a javascript library that handle this specialy ? Sorry if my question is look silly.

  • mistercoffee says:

    @Richard Clark — “I’ve fixed a few typo’s, are there any I’ve not got?”

    You made a typo in the word “typo’s” (should be “typos”).
    I know you said you’re not a journalist, but you’re a smart guy!
    This was a joke, right? Please?

    Great article, no offense intended! :D

  • Lori says:

    Thanks for the article. How does one style multiple instances of footer on a page without confusing the browser ?

  • Jemmy says:

    A short master class…thanks. I am guilty of a few of these, so off to refactor!

    I think the challenge is generalized tag names that have specific applications. Of course it’s the developer’s responsibility to read the standard, but I can understand a developer intuitively misusing some of the new tags, such as using <nav> for footer links, or any set of links for that matter. Thinking semantically (and intuitively I would argue), I would wonder why, when looking at a page with several lists of links, that some merit a <nav> tag and some don’t. And because they are necessarily somewhat subjective, validators can’t really advise us of possible misuse, i.e., “Are you sure you need a <nav> element inside the <footer> element?”

  • Ale Gadpen says:

    Wow!! Super great article!! Thx for the enlightment!

  • Yousaf says:

    Logo should have its own tag, ideally.

  • Lori says:

    Great idea, Yousaf

  • LXander says:

    Well, watching HTML5 courses before that article I thought – i can take it & everything’s fine… but now… i’m not sure … html5 it’s too complex :(
    So, I guess — we’ll haveA LOT OF MISTAKES (in semantics markup) for quite a very looonG time…
    But nevertheless… html5 rules (it’s Pity- Not4Me@thisTime)

  • Joe Seifi says:

    Another point regarding wrapping a single heading tah with a header tag, in addition to what Anthony pointed out already:

    Per http://diveinto.html5doctor.com/semantics.html

    Let me put it another way. HTML 4 has no generic heading element. It has six strictly numbered heading elements, –, which must be nested in exactly that order. That kind of sucks, especially if your page is “assembled” instead of “authored.” And this is the problem that HTML5 solves with the new sectioning elements and the new rules for the existing heading elements. If you’re using the new sectioning elements, I can give you this markup:

    A syndicated post

    Lorem ipsum blah blah…

    and you can copy it and paste it anywhere in your page without modification.

    So what gives?

    Great article by the way.

  • Pen says:

    Gee I wish I had found your site sooner – What great insight and useful info – Thanks for sharing!

    I am still not totally clear on when to use though – if at all?

  • Chris says:

    This article’s a big help. Thanks.

  • Yop says:

    blah blah blah, if it display as i want why do i have to worry about type overload it’s cleaner to read this way and section are quicker to target great with selectors if they are used like wraper.

    for boolean attribute it’s cleaner to use as you suggest but is it really working evrywhere ?

  • Mia says:

    Thanks! I really needed this.

  • Really good article.. note down some more information to follow..

  • Christoph says:

    Great article, thx!

  • Mark says:

    Given the ambiguity around using these supposedly more ‘semantic’ sectioning elements, I have to wonder what are the real benefits conferred by using them if most people are going to get it wrong and end up with a confusing document outline? In particular, how does it help people using assistive software that parse the outline (e.g. JAWS)?

    Accessibility seems to have been forgotten in the rush to html5:
    http://www.accessibleculture.org/articles/2011/10/jaws-ie-and-headings-in-html5/

  • Don’t agree with the header examples. Writing HTML is not only about writing what lies in front of you. Even if you only have a h1 in your blog post header, still include the header tags. There’s a very big and real possibility that at one time you’ll need other elements in there (in fact, you should – pulbish dates are essential) so structurally it makes sense to add a container. Fiddling with structures is not very future-proof, so it’s best to keep to certain best practices.

    Not only that, but showing some consistency throughout our code would make us look better with back-end developers.

  • Thoufeeq says:

    Bookmarked for future reference….

    Thanks

  • manoj says:

    wipe out my confusion to read this article…

  • matejlatin says:

    well I’ve noticed some of my frequent errors but I’m still learning the HTML5 so this article was very useful, thanks.

    I really didn’t know that about the css link type …

  • Mr H says:

    This site doesn’t render correctly on IE8! I cannot take you seriously! Fail!

  • Erik says:

    You make many valid points and I’m not saying anything is wrong, but people put too many “semantics” into HTML code. Sure HTML can describe much more than a “pretty picture” page for someone’s website, but ideas like for instance, doing the cardinal sin of using tables for layout, sure its “bad” practice and not what tables are meant for but people know how to use them to keep things lined up without having to do all that CSS styling (and still maybe having it look wrong). In the “real world” of business, you’re going to have a boss who isn’t going to care how “semantically correct” a web application interface page is, as long as it works. He’s not going to care if you used a table to keep everything lined up, as long as you produce results quickly. That’s why so many people do things “the wrong way”. It’s not that they wouldn’t do it right if they had the time, but learning the “correct” way to use everything takes a lot of time, and then you’re having someone sit there and debate something as trivial as whether he misused the or any other container element.

  • P Mc says:

    It wasn’t that long ago that the push away from table based design lead to container style design in an attempt to clear out all the extraneous code and separate content from structure. Then along comes HTML5 that introduces a whole library of new tags and elements intended to create an even more structured approach to markup but HTML5 is also intentionally loosey-goosey, allowing for an “anything goes” approach to writing code and as author Rich points out we’re spoilt in the wide array of elements we can choose from to structure our markup which will inevitably lead to an equally wide array to approaches and choices. All that means is there will be a complete lack of structure in the end. Ultimately, the only thing HTML5 will accomplish is to reintroduce extraneous code, and cause confusion where it meant to create structure.

    I like some of the functionality that HTML5 introduced (e.g. canvas, video etc.) but I think it failed in every other respect and I hope many of the more useless elements become deprecated in the inevitable HTML6

    and +1 for Eric’s comments as well.

  • Daniel Ronkainen says:

    Hello, Richard Clark.
    I have a question about the structure of a regular website if it is for example divided in diffrent anchor section.

    Lets say it’s a site for an building company and you go into a page named “For the home” and under this page there are 4 outher anchor sections “Conservatories, Patios, Stairs, and Doors” all these are associated with “For the home” page. How would the HTML5 structure look like here?

    Should I use article and section nested inside? To specify that this content is related in some way even tho its not a blog or news sites.

    Becouse the article is self-contained and the section groups together thematically-related content and all these anchor pages are related in some way.

  • ak says:

    i am new in php. i have query as Can we use head tag in between div tag as:
    <html>
    <head>
    <script>
    </script>
    </head>
    <body>
    <section>
    <div>
    <head>
    <script></script>
    </head>
    <body>
    <form></form>
    </body>
    </div>
    </section>
    </body>
    </html>

    is it correct way? if not then what is another option?

  • Paul says:

    I think it is easy to be a bit over pedantic as well as under pedantic.
    eg. your article says that it isn’t worth using the tag if say you just have something like some text wrapped in tags.

    BUT…

    The point of html is that it is a front end technology that can take content from a backend server to display.
    eg. maybe the tags and text are generated by a database that may at some point include more text and tags, if the content editor adds them.

    What you should do is assess the probable content that will be placed between the tags over a period of time. Taking snapshots, is likely to result in incorrect assessment or over the top backend coding.

    Common sense should prevail.

  • @Niels, some people would argue that publish dates should be in a footer. No example is going to be perfect and you’re right we have to plan for the future but if you’re using a CMS then it’s no trouble to go in and edit the template to make the change site wide.

    @Erik, you’re right there’s a level of practicality to be applied. I work for a web agency and have worked in house previously, I know the pressures that coe with that. However, at the same time we have to keep on learning. As you read more articles, write more markup patterns and code more often you’ll become more productive so your boss will be happy (even if he doesn’t care how it’s built) because you’re more profitable. Aside from that, for me though, it’s about taking pride in my work and not just bashing out whatever code I can to get by and keep the suits happy.

    @Paul, I think some of your comment got stripped but I know what you mean. What you don’t want is empty tags though, your server side code shouldn’t render them if there’s no content included. Coding defensively I guess. But yes, you’re right, common sense should prevail and as always, it depends.

  • Montathar Faraon says:

    I have to say that you write in an inspiring way. Good work!

    But.. I find it interesting that you recommend NOT to use for pagination controls while your colleague Tom Leadbetter says that CAN BE considered for pagination according to the following link: http://html5doctor.com/nav-element/

    Any further reflections about this?

  • Joe says:

    Now that hgroup is deprecated (rightfully so), you may want to update this article. Great read btw.

  • Wow. I appreciated this article, Rich, but when I hit the comments and immediately saw Ryah’s response, I knew where the real hawtness of this page was going to lie.

    Oli’s link to “your another medical blog” was pure win.

    @Yop,

    blah blah blah, if it display as i want why do i have to worry about type overload it’s cleaner to read this way and section are quicker to target great with selectors if they are used like wraper.

    Lol! True, so let’s extend this logic and really simplify our web dev. Export the PSD design into a single jpg or png and you have three elements:

    <body>
    <img src="&quot>>
    </body>

    It will display exactly as you want and you won’t even need to test it!

    @Erik,

    You make many valid points and I’m not saying anything is wrong, but people put too many “semantics” into HTML code. … In the “real world” of business, you’re going to have a boss who isn’t going to care how “semantically correct” a web application interface page is, as long as it works. He’s not going to care if you used a table to keep everything lined up, as long as you produce results quickly. That’s why so many people do things “the wrong way”.

    While I agree with you that people can spend too much time worrying about the semantic import of this or that element (relative to the payoff of choosing the correct one), let’s extend your logic as well (and see the next three-element site code above. Get ‘er done, right!)

    By your logic, fast results, but not correct ones matter. The problem, of course… Actually, let’s just do a thought experiment. Your boss’s car breaks down, and he wants it repaired. You use duct tape, because he doesn’t care about how it’s fixed, he just wants it to “work” quickly.

    You duct tape it up, invite him in and then send him off down the road. You do understand how that journey is going to end, right?

  • @Joe, thanks for the reminder, I’ve included a note about hgroup.

  • @Joe, thanks for the reminder, I’ve included a note about hgroup.

  • Peter Devoy says:

    A helpful article, thanks!

    Of course, we could always avoid the div/section layout issues by using tables…

    Just kidding ;D

  • @Peter: You really scared me there. There is obviously something wrong with html5doctor.com’s stylesheets when it comes to article comments, and in this case your “Just kidding” paragraph was rather well hidden…

  • Nurul Imam says:

    How to change article section to main element ?

    <main role=”main”>
    <article>

    or

    <article>
    <main role=”main”>

  • Nurul Imam says:

    Thanks Steve, But how to styling role=”main” ?
    Ex. main {} ?

  • Naurul: You use CSS attribute selectors for that, like


    <style>
    [role=main] {
    color: red;
    }
    </style>

    which will match all HTML elements with a role attribute set to main or


    <style>
    main[role=main] {
    color: red;
    }
    </style>

    which will only match a main element with a role attribute set to main.

    But I don’t understand why you want to do that, since role=main is probably only found on the main element, so surely


    <style>
    main {
    color: red;
    }
    </style>

    is enough?

  • Nurul Imam says:

    Yes, i’m use <main> not <main role=”main”> because I do not know how to styling attribute selector <main role=”main”>.
    Thank you, I will try to change

  • Ray says:

    I think you might be missing a key point at the end of your section called “Your logo is not a figure” when you finally sum up by saying, “All you need is this:”…

    The whole point (I thought) was to show that you can usually best use without wrapping it in a element … but in the final example, you neglect to use the attribute at all!

  • Reinaldo César says:

    Okay, it’s wrong for me to add my classes in sections in order to style each section and their contents?

  • @Reinaldo: It is not wrong for you to add classes to sections in order to style them; what @Dr. Clark is saying is don’t use the section tag to create generic wrapper elements to hang style hooks from. That has traditionally been the role of div (block-level) or span (inline), and it remains their role in HTML5.

    As @Dr. Clark says, “One of the most common problems I see in people’s markup is the arbitrary replacement of <divs>” (emphasis added).

  • Edd says:

    This is one way to educate people of the improper use of HTML 5.

    a fair amount of what is said in this article is actually wrong.

    And is also contradictory to another HTML5 doctor post

    http://html5doctor.com/the-article-element/

  • Alex says:

    Today it make sense to use:

    and style the ‘div id=header’ instead of the ‘header’ tag to avoid compatibility problem?

  • Carlos says:

    Ok we’re by the end of the 1st quarter of 2015. According to a warning above, the hgroup tag was removed from the spec (W3C spec i suppose), but WHATWG’s spec still has it. So, is it safe to use it? i used it before, stopped using as per W3C’s spec… but now i’m not sure of what to do.

  • Leave a Reply to Jeffrey Barke

    Some HTML is ok

    You can use these tags:
    <a href="" title="">
    <abbr title="">
    <b>
    <blockquote cite="">
    <cite>
    <del datetime="">
    <em>
    <i>
    <q cite="">
    <strong>

    You can also use <code>, and remember to use &lt; and &gt; for brackets.