Code Style Guide: HTML

jcamenisch edited this page Mar 25, 2012 · 11 revisions
Clone this wiki locally

This is the Code Style guide for HTML. See the main Code Style Guide page for other languages.

Indentation

Use an indent of 2 spaces, with no tabs.

Doctype and Character Encoding

Use the HTML5 doctype and the UTF-8 character encoding for all templates. Specify each document’s character encoding by using the <meta charset="utf-8"> element, which must be the very first element in <head>.The syntax is as follows:

<!DOCTYPE html>

<html lang="en">

<head>
  <meta charset="utf-8">
  <title></title>
  ...

Capitalization & Syntax

Because we’re using an HTML doctype, use HTML-style syntax rather than XHTML-style syntax.

HTML elements should be set in lowercase.

<br>    <!-- Okay -->
<br/>   <!-- Not Okay -->
<br />  <!-- Not Okay -->
<BR>    <!-- Not Okay -->

CSS ID names should be in lowerCamelCase.

<div id="pageContainer">

Class names should be in lowercase, with words separated by underscores.

<div class="my_class_name">

Attribute values must be enclosed in double quotation marks.

<div class="my_class_name"><!-- Okay -->
<div class=my_class_name><!-- Not Okay -->

Permitted Elements

The following elements are valid in both HTML 4 and HTML 5, and hence can be used safely in ThinkUp’s templates:

<!-- -->, <!DOCTYPE>, <a>, <abbr>, <address>, <area>, <b>, <base>, <bdo>, <blockquote>, <body>, <br>, <button>, <caption>, <cite>, <code>, <col>, <colgroup>, <dd>, <del>, <div>, <dfn>, <dl>, <dt>, <em>, <fieldset>, <form>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <head>, <hr>, <html>, <i>, <iframe>, <img>, <input>, <ins>, <kbd>, <label>, <legend>, <li>, <link>, <map>, <menu>, <meta>, <noscript>, <object>, <ol>, <optgroup>, <option>, <p>, <param>, <pre>, <q>, <samp>, <script>, <select>, <small>, <span>, <strong>, <style>, <sub>, <sup>, <table>, <tbody>, <td>, <textarea>, <tfoot>, <th>, <thead>, <title>, <tr>, <ul>, <var>

The following elements have been deprecated in HTML 5. Please do not use them in ThinkUp’s templates:

<acronym>, <applet>, <basefont>, <big>, <center>, <dir>, <font>, <frame>, <frameset>, <isindex>, <noframes>, <s>, <strike>, <tt>, <u>, <xmp>

The following elements are new in HTML 5 and browser support for them is spotty or nonexistent. For now, please do not use them in ThinkUp’s templates:

<article>, <aside>, <audio>, <canvas>, <command>, <datagrid>, <datalist>, <datatemplate>, <details>, <dialog>, <embed>, <eventsource>, <figure>, <footer>, <header>, <mark>, <meter>, <nav>, <nest>, <output>, <progress>, <ruby>, <rp>, <rt>, <rule>, <section>, <source>, <time>, <video>

Validation

Before committing changes to template files, please make sure that the HTML still validates:

1. Go to http://validator.nu/
2. If the template or page you’re modifying is public, select Address from the dropdown menu and enter the page URL in the text field to the right. If the template or page you’re modifying is password-protected, select Text field from the dropdown menu, view source of the template or page you’re modifying, select all and copy, then paste into the textarea to the right.
3. Optional: Select Pedagogical: suitable for teaching purposes from the dropdown menu to the right of Profile.
4. Optional: Check the box next to Show Source.
5. Click the Validate button.

Character Escaping

You must escape ampersands that appear in URL query strings written in HTML, otherwise your HTML will fail validation. In particular, a URL such as this:

<!-- Not Okay -->
http://example.com/search?name=detail&uid=165

must become this:

<!-- Okay -->
http://example.com/search?name=detail&amp;uid=15

This is true even inside href attributes of a elements or src attributes of script elements:

<!-- Okay -->
<a href="http://example.com/search?name=detail&amp;uid=16">Search</a>
<script type="text/javascript" src="http://bit.ly/javascript-api.js?version=latest&amp;login={$cfg->bitly_login}&amp;apiKey={$cfg->bitly_api_key}"></script>