Skip to content

Latest commit

 

History

History
200 lines (146 loc) · 6.9 KB

html-styleguide.md

File metadata and controls

200 lines (146 loc) · 6.9 KB

HTML Styleguide

Best practices and guidelines for writing HTML with approachable formatting, syntax, and more.

General

  • Practicality over purity: Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.
  • JavaScript generated markup: Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.

Syntax

  • Use soft-tabs with two spaces. Spaces are the only way to guarantee code renders the same in any person’s environment.
  • Nested elements should be indented once (two spaces).
  • Always use double quotes, never single quotes, on attributes. Even though quotes around attributes is optional, always put quotes around attributes for readability.
  • Paragraphs of text should always be placed in a <p> tag. Never use multiple <br> tags.
  • Items in list form should always be in <ul>, <ol>, or <dl>. Never use a set of <div> or <p>.
  • Every form input that has text attached should utilize a <label> tag. Especially radio or checkbox elements.
  • Don’t include a trailing slash in self-closing elements (e.g. <br>, <hr>, <img>, and <input>), as the HTML5 spec says they’re optional.
  • Don’t omit optional closing tags (e.g. </li> or </body>).
  • Avoid writing closing tag comments, like <!-- /.element -->. This just adds to page load time. Plus, most editors have indentation guides and open-close tag highlighting.
  • Don’t set tabindex manually—rely on the browser to set the order.
<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Enforce standards mode and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Language attribute

From the HTML5 spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document’s language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec.

Head to Sitepoint for a list of language codes.

<html lang="en">
  <!-- ... -->
</html>

IE compatibility mode

Internet Explorer supports the use of a document compatibility <meta> tag to specify what version of IE the page should be rendered as. Unless circumstances require otherwise, it’s most useful to instruct IE to use the latest supported mode with edge mode.

For more information, read this awesome Stack Overflow article.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Character encoding

Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding. When doing so, you may avoid using character entities in your HTML, provided their encoding matches that of the document (generally UTF-8).

<head>
  <meta charset="UTF-8">
</head>

CSS and JavaScript includes

Per HTML5 spec, typically there is no need to specify a type when including CSS and JavaScript files as text/css and text/javascript are their respective defaults.

HTML5 spec links

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Attribute order

HTML attributes should come in this particular order for easier reading of code.

  • class
  • id, name
  • data-*
  • src, for, type, href, value
  • title, alt
  • role, aria-*

Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second.

<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Boolean attributes

Many attributes don’t require a value to be set, like disabled or checked, so don’t set them.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

For more information, read the WhatWG section.

Lean markup

Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. For example:

<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

Forms

  • Lean towards radio or checkbox lists instead of select menus.
  • Wrap radio and checkbox inputs and their text in <label>s. No need for for attributes here—the wrapping automatically associates the two.
  • Form buttons should always include an explicit type. Use primary buttons for the type="submit" button and regular buttons for type="button".
  • The primary form button must come first in the DOM, especially for forms with multiple submit buttons. The visual order should be preserved with float: right; on each button.

Tables

Make use of <thead>, <tfoot>, <tbody>, and <th> tags (and scope attribute) when appropriate. (Note: <tfoot> goes above <tbody> for speed reasons. You want the browser to load the footer before a table full of data.)

<table summary="This is a chart of invoices for 2011.">
  <thead>
    <tr>
      <th scope="col">Table header 1</th>
      <th scope="col">Table header 2</th>
    </tr>
  </thead>
  <tfoot>
    <tr>
      <td>Table footer 1</td>
      <td>Table footer 2</td>
    </tr>
  </tfoot>
  <tbody>
    <tr>
      <td>Table data 1</td>
      <td>Table data 2</td>
    </tr>
  </tbody>
</table>

Credits