Skip to: Navigation | Content | Sidebar | Footer


Weblog Entry

Boilerplate

January 31, 2011

If you’re not aware of it yet, HTML5 boilerplate is a fantastic starting point when creating a new site with its namesake markup language.

But where Boilerplate focuses on basic document setup, external files, scripts, and bug fixes, it strikes me that it doesn’t do much hand-holding when it comes to basic document semantic patterns. As I’ve been working more and more HTML5 into my projects, I’m noticing a common template emerging.

I’m sharing this as a minimum viable starting point since I’m still getting comfortable with the new semantics myself. Combined with Boilerplate, I’m feeling more and more confident that I’m beginning to use HTML5 properly. Don’t consider it canonical by any means, there’s likely a lot of room for improvement and it’s most certainly wrong in places. Comments / suggestions for improvement are more than welcome.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>pageTitle</title>
  <link rel="stylesheet" href="default.css">
  <script src="default.js"></script>
</head>
<body>


<div id="accessibility">
  <a href="#nav">Skip to Navigation</a> |
  <a href="#main-content">Skip to Content</a>
</div>


<header role="banner">
  <div class="masthead">
    <a href="#"> ....site title or logo, purposely not an h1.... </a>
  </div>
  <nav id="nav">
    <ul>
      <li><a href="#">
        ....main site nav list....
      </a></li>
    </ul>
  </nav>
  <div id="secondary-nav">
    <ul>
      <li><a href="#">
        ....other non-primary navigation doesn't belong in a nav element....
      </a></li>
    </ul>
  </div>
</header>


<section id="main-content" role="main">
  <h1> ....page title here.... </h1>
  <article>
    <header>
      <h2>....article heading if needed....</h2>
      <h3>....article sub-heading if needed....</h3>
    </header>
    ....article content here....
  </article>
  <article>
    ....use more article elements if appropriate; if not, I still use divs....
  </article>
</section>


<aside id="sidebar">
   ....site sidebar here....
</aside>


<footer>
  .... footer content here ....
</footer>


</body>
</html>

You’ll notice I’m a believer in reserving h1 headings for the page title, and not the site / company name. I’m still not sure I get how to use the revised heading order so I’m sticking with old school h1-h6 for now.

Thanks to the pave the cowpaths philosophy that guided HTML5 development, it feels almost too easy. It’s not much more than a tweak to my previous XHTML template: change a few ids to their corresponding elements here and there, replace various divs with sections, articles and asides where relevant, and add / remove extra attributes where necessary. Done.


January 31, 17h

I also tried to make default HTML5 template with just the basic stuff like CSS Reset, CSS Media Queries and print CSS https://github.com/vladocar/HTML5-Mini-Template .

I’m not sure that the my HTML5 is semantically correct, so it would be nice to have more opinions and discussions about semantic HTML5 .

2
DRoss says:
January 31, 17h

Using section for wrapping content isn’t really what it’s for. For wrapping general content using a div is ideal. section has it’s purposes but not going to go into all that - check the link below for tons of useful info.

Same thing as using aside for sidebar. It can be used as a sidebar but is really to be used for smaller bit of content related to a larger piece of content.

If you really want to be semantic and use it correctly there’s much more thought that goes behind choosing which element to use rather than just changing divs into sections and sidebars into asides.

Check out http://html5doctor.com for a lot of nice tips.

-DRoss

CHJJ says:
January 31, 17h

Dave, it makes perfect sense to use the sitename/logo for as the first h1 of the page if you read the HTML5 document outlining algorithm: http://www.whatwg.org/specs/web-apps/current-work/multipage/sections.html#outlines

The first explicit section’s h1 will never become the title of the document. It doesn’t make sense to intentionally avoid using an h1 in a sectioning root that has child sections - if you do, the section/document will remain untitled or be given an implicit title anyway.

Chad says:
January 31, 18h

Is there a reason that you’re using a div for the secondary navigation rather than a nav like you do for the primary? IMO it would be very logical to have:

<nav id=”primary”>
</nav>
<nav id=”secondary”>
</nav>

Also, I agree w/ the use of your h1 for the document rather than for the logo/site name. HTML semantics is about documenting, not branding… but I’m curious as to if/how it impacts SEO.

January 31, 19h

Putting scripts in the bottom of the page by default is a good habit to be in. Scripts block the browser from rendering while they execute due to the chance that the script might perform a document.write() or similar page-modifying tasks. By placing scripts after the majority of page content you guarantee that the content will be rendered before the script halts the show. So while the page isn’t done and the loading spinner may still spin, at least people have a useful web page to spend their time with.

kaidez says:
January 31, 19h

Hmmm…you should definitely do what you want to do, but I believe that semantics call for an h1 inside that header tag that’s inside the article tag. And man, is HTML5 big on semantics!!!

CHJJ says:
January 31, 20h

Aside from the flawed omission of the sitename as an H1 (mentioned this in a comment that hasn’t been approved yet :/), I’m also confused by the “secondary-nav” div. The use of an ASIDE element is justified in its place, depending on what it contains. Otherwise, why not just leave the UL unwrapped?

Daniel says:
January 31, 23h

If you are using a header tag I’m pretty sure you need to have at least one h1-h6 tag present. Adding a role=”banner” attribute to your masthead on page gives it more semantic meaning as to what it is for this current page.

You can also use the role=”main” attribute to distinguish your main content section from the rest. Using roles will eventually allow you to drop your accessibility navigation altogether as assistive technology will recognise the areas of your document. Your footer tag could have a role applied to it too.

I would agree with the other commenters here and wrap your navigation items in a nav tag.

February 01, 06h

We also have a boilerplate for HTML5 specific to WordPress, complete with plugins and a lot of extras: http://html5.mimoymima.com

Special attention is paid to accessibility and semantics and the document outline. ENJOY and SHARE :D

February 01, 07h

I’m already trying to use (almost) only h1s on Gastero Prod, and even created a stylesheet for multi level sectioned h1 styles. The (obvious) name is HTML5-Titles-Inception, and freely available/forkable on Github: https://github.com/nhoizey/HTML5-Titles-Inception

Dave S. says:
February 01, 08h

@Vladimir Carrer – upon first glance it looks like we’re sharing a lot of common patterns between our templates. Major differences appear to be heading order, placing nav outside header, and how many items we each define within the page. I think both approaches potentially work, though I’d also be interested in hearing various arguments for and against how your template is setup.


@DRoss – yes, I read HTML5 Doctor, do you? I’ll grant perhaps section usage could be debated, but here’s an article where they state the opposite of what you did about aside usage:

http://html5doctor.com/aside-revisited/


@CHJJ @kaidex – re: not using h1 for a site title, this isn’t new to HTML5. For years now we’ve been debating whether to reserve it for the page title or not. For accessibility and SEO reasons, there appears to be a solid argument against using it as the site title. It’s a habit I’ve been in for a while, and I’d have to see some pretty strong counter-arguments to break it. Commenters saying it should be done otherwise isn’t enough to sway me.


@Chad @CHJJ @Daniel – re: wrapping the secondary navigation, have you guys read the spec on nav element usage?

http://dev.w3.org/html5/spec/Overview.html#the-nav-element

Links like login / contact / home page etc., things I’d consider secondary navigation, those don’t belong in their own nav element.


@Daniel – good call about role attributes, I’ve added those to the example.

CHJJ says:
February 01, 09h

Dave, I understand that - that’s what I’m saying: The positions that have been held for years on either side of this argument need to be reevaluated in the face of HTML5. Omitting a sitename as the H1 in the body doesn’t make sense if you also have a heading inside an explicit (main content) section - the body/document gets an implied title anyway according to the outlining algorithm.

On the secondary navigation, I don’t think I said anything about a nav element in my previous comments.

Bernard says:
February 01, 22h

Is there a reason you kept the accessibility links outside of the banner header instead of inside? I’ve been debating on whether it should stay out as its own or not. The spec seems to allow it and possibly encourage it; though, I’m not sure how screen readers and search engines would treat them differently.

February 02, 14h

Personally, I wouldn’t use a section element for the role=”main” chunk of content.

Remember that the body element is also sectioning content (like section, article, nav and aside) so what you’ve got in your template is a piece of sectioning content (body) that has a header and a footer but no actual content (apart from the #accessibility div).

I usually tend to attach role=”main” to a div myself.

SJL says:
February 03, 01h

Thanks for the starting point Dave. Like you I’ve been using the boilerplate template and still trying to get my head around the new semantics in HTML5. I think I have adapted a similar structure as you have used here in new sites I’m developing. I also agree with you on the use of H1’s as page titles! Cheers

February 03, 02h

Dave,

Shouldn’t the character set definition be set _before_ the title element? Otherwise, how will it know what character set to use?

Gerasimos says:
February 03, 02h

As a professional dealing mostly with non-english content i have to agree with Tim above. Character set should be declared before the title element.

Dave S. says:
February 03, 12h

@Jeremy Keith – you’re likely right, switching that particular section to a div is probably the right way to go.

@Tim Huegdon @Gerasimos – good call. Swapped.

Stephanie says:
February 04, 23h

I’d add role=”navigation” and role=”contentinfo” too :)

20
jojomonkey says:
February 05, 16h

can you swing this by paul irish and divya from html5boilerplate.com?
maybe they can chime in - would be interested.

21
Ingwa says:
February 05, 19h

I cringe at the thought of an h1 being a logo. A company logo is not an h1, it’s an image. Search engines will completely ignore what is inside it, image or otherwise if they don’t believe there’s any “content” contained within it. http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/

Gonzo says:
February 07, 23h

One more argument for not using section for the main content - sometimes you will have only one article element on the page and you will want it’s header to be h1 - a single post page for example. This will leave the section element without it’s own header, and we all know sections need headers.

February 08, 13h

I agree with your thoughts here and I really love your blog! I’ve bookmarked it so that I can come back & read more in the future.

CHJJ says:
February 08, 14h

Ingwa, you’re wrong. Things don’t work that way currently if you’re using explicit sections for your content. Read the document outlining algorithm. A sitename in an h1 replaced with a logo is perfectly reasonable, and I would even argue that it is necessary.

Gonzo, you’re right. If Dave isn’t using the sitename as an H1 for the BODY, he shouldn’t be using an explicit section for his content.

On another note, there are also other things wrong with this boilerplate, such as the use of HEADER as if it were an HGROUP. These boilerplates are very harmful in my opinion.

Gonzo says:
February 08, 23h

CHJJ, I think the header element inside the article is OK. Since this is just a boilerplate, when used properly, additional information may go in the header. Also there are strong opinions against the hgroup element and I agree that when you have h1 and h2 inside a header, adding a hgroup element is redundant.

CHJJ says:
February 09, 08h

The arguments against HGROUP stem from it’s awkward unintuitive usage, but that’s a different story - the fact is, Dave is using HEADER here as if it were an HGROUP (regardless of whether the HGROUP element was a good idea in the first place). A HEADER element does not remove the trailing heading content from the document outline. HEADER and HGROUP have completely different meanings. It does not perform the same function: it produces a completely different document outline. That’s pretty much all there is to it. There’s no wiggle room there.

February 09, 17h

If you haven’t run your suggested template through an html5 document outline parser, you might not be aware that there are a couple of “holes” in it.

Compare: http://members.optus.net/englesaxe/about/html5_06.html with
http://members.optus.net/englesaxe/about/html5_07.html

To see an html5 document outline, install the Chrome extension at http://code.google.com/p/h5o/ .

More specifically, the html5 document outline parser expects a heading in every sectioning element except ‘footer’.

This may seem unnecessry or obsessive at first. But for users who depend on screen readers, it’s a boon. Think about this. I know a sidebar is a sidebar because I can see that it sits to one side. That position on the page tells me that the information contained therein is secondary in some way, ancillary to the main content. A screen reader doesn’t know that. But a suitable heading will make it clear: “Sidebar” or “Secondary Content” or “Related Resources” etc. Similarly with a menu: how does a user know that a list is the site navigation unless he/she can see that it’s placed prominently with an eye-catching design, or a suitable title signals its role? Bottom line: we should place a suitable heading in each nav and aside and header, but use CSS {position:absolute; top:0; text-indent:-9000em} to remove those headings from the viewport.

However, if you put a heading in header, that becomes the “body title”. That will place many developers in a quandary, because we expect the top of the document outline tree to be our page heading. But our page heading (in most cases) will be in the article (or section) - which is one level down in the document outline. Perhaps the best solution at present is to put some combination of the site name, section name and page name in a heading in header, but remove it from the viewport (see above).

February 09, 19h

http://csswizardry.com/2011/01/the-real-html5-boilerplate/ Harry Roberts has an excellent point on why 681 lines of code (albeit good code) is not a “boilerplate.”

29
Adrian Neilson Hall says:
February 10, 15h

Great article Dave. Thanks. You really got me thinking about html5 templates. And digging into the heading hierarchy.

I was surprised to find that marking your page title up with h1 no longer guarantees that it will sit at the top of the html5 document outline tree*. What are your thoughts?

(* That honour goes to the first non-nested heading or the main heading within the first non-nested header.)