Code Standards: Markup

All the latest news from across the site is available here!

Code Standards: Markup

John Stray
July 20th, 2015

The first component of any web page is the tag-based mark-up language of HTML. The Hyper Text Markup Language has a sordid history but has come into its own in the last few years. After a lengthy experimentation with the XML-based XHTML variant, the industry has accepted that HTML is the future of the web.

Mark-up defines the structure and outline of a document and offers a structured content. Mark-up is not intended to define the look and feel of the content on the page beyond rudimentary concepts such as headers, paragraphs and lists. The presentation attributes of HTML have all been depreciated and style should be contained in style sheets.


HTML5 is a new version of HTML and XHTML. The HTML5 draft specification defines a single language that can be written in HTML and XML. It attempts to solve issues found in previous iterations of HTML and addresses the needs of web applications, an area previously not adequately covered by HTML.

We will use the HTML5 Doctype and HTML5 features when appropriate.

We will test our mark-up against the W3C Validator, to ensure that the mark-up is well formed. 100% valid code is not a goal, but validation certainly helps to write more maintainable sites as well as debugging code. The aim is not to guarantee code is 100% valid, but instead to ensure the cross-browser experience is fairly consistent.

HTML5 Boilerplate

HTML5 Boilerplate is a professional front-end template for building fast, robust and adaptable web applications or sites. It is strongly recommended that you use this project for the core template of your website project.

The project is the product of many years of iterative development and combined community knowledge. It does not impose a specific development philosophy or framework, so you're free to architect your code in the way that you want.

HTML5 Boilerplate is supported by recent versions of the most major browsers, such as Google Chrome, Mozilla Firefox, Microsoft Internet Explorer 8+, Opera and Apple Safari. This doesn't mean that it can't be used in older browsers, just that it ensures compatibility with the browsers mentioned herein.


A proper Doctype which triggers standards mode in your browser should always be used. Quirks mode should always be avoided.

A nice aspect of HTML5 is that it streamlines the amount of code that is required. Meaningless attributes have been dropped, and the DOCTYPE declaration has been simplified significantly. Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness standards in XHTML.

<!DOCTYPE html>

Character Encoding

All mark-up should be delivered as UTF-8, as its the most friendly for internationalization. It should be designated in both the HTTP header and the head of the document.

Setting the character set using <meta> tags.

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

In HTML5, just do:

<meta charset="utf-8">

General Markup Guidelines

The following are general guidelines for structuring your HTML mark-up. Authors are reminded to always use mark-up which represents the semantics of the content in the document being created.

  • Use actual <p> elements for paragraph delimiters as opposed to multiple <br> tags.
  • Make use of <dl> (definition lists) and <blockquote>, when appropriate.
  • Items in list form should always be housed in a <ul>, <ol> or <dl>; never in a set of <div>s or <p>s.
  • Use <label> fields to label each form field, the for="" attribute should associate itself with the input field so users can click the labels.
  • Do not use the size attribute on your input fields. The size attribute is relative to the font-size of the text inside the input. Instead, use CSS width.
  • Place an html comment on some closing <div> tags to indicate what element you're closing. It will help when there is lots of nesting and indentation.
  • Tables shouldn't be used for page layout. I still see this a lot. That's not their intended purpose.
  • Use microformats and/or microdata where appropriate, specifically hCard and adr.
  • Make use of <thead>, <tbody> and <th> tags (and scope attribute) when appropriate.
    Table mark-up with proper syntax (THEAD, TBBODY, TH [scope])
    <table summary="This is a chart of year-end returns for 2005.">
          <th scope="col">Table header 1</th>
          <th scope="col">Table header 2</th>
          <td>Table data 1</td>
          <td>Table data 2</td>
  • Always use title-case for headers and titles. Do not use all caps or all lower-case titles in mark-up, instead apply the CSS property text-transform:uppercase/lowercase.

Quoting Attributes

The HTML5 specification defines quotes around attributes as optional. For consistency with attributes that accept white-space, all attributes should be quoted.

<p class="line note" data-attribute="106">This is my paragraph of special text.</p>