HTML BEST PRACTICES

6 min readAug 6, 2020

1.General

Start with DOCTYPE

DOCTYPE is required for activating standard mode.

Bad:

<html>
  ...
</html>

Good:

<!DOCTYPE html>
<html>
  ...
</html>

Don’t use legacy or obsolete DOCTYPE

DOCTYPE is not for DTD anymore, be simple.

Bad:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">

Good:

<!DOCTYPE html>

Don’t use XML Declaration

Are you sure you want to write XHTML?

Bad:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE html>

Good:

<!DOCTYPE html>

Don’t use character references as much as possible

If you write an HTML document with UTF-8, almost all characters (including Emoji) can be written directly.

Bad:

<p><small>Copyright &copy; 2014 W3C<sup>&reg;</sup></small></p>

Good:

<p><small>Copyright © 2014 W3C<sup>®</sup></small></p>

Escape `&`, `<`, `>`, `"`, and `'` with named character references

These characters should escape always for a bug-free HTML document.

Bad:

<h1>The "&" character</h1>

Good:

<h1>The &quot;&amp;&quot; character</h1>

Use numeric character references for control or invisible characters

These characters are easily mistaken for another character. And also spec does not guarantee to define a human-readable name for these characters.

Bad:

<p>This book can read in 1 hour.</p>

Good:

<p>This book can read in 1&#xA0;hour.</p>

Put white spaces around comment contents

Some character cannot be used immediately after comment open or before comment close.

Bad:

<!--This section is non-normative-->

Good:

<!-- This section is non-normative -->

Don’t omit the closing tag

I think you don’t understand a rule for omitting closing tag.

Bad:

<html>
  <body>
    ...

Good:

<html>
  <body>
    ...
  </body>
</html>

Don’t mix empty element format

Consistency is key for readability.

Bad:

<img alt="HTML Best Practices" src="/img/logo.png">
<hr />

Good:

<img alt="HTML Best Practices" src="/img/logo.png">
<hr>

Don’t put white spaces around tags and attribute values

There is no reason for doing this.

Bad:

<h1 class=" title " >HTML Best Practices</h1>

Good:

<h1 class="title">HTML Best Practices</h1>

Don’t mix character cases

It gives consistency also.

Bad:

<a HREF="#general">General</A>

Good:

<a href="#general">General</a>

Also Good:

<A HREF="#general">General</A>

Don’t mix quotation marks

Same as above.

Bad:

<img alt="HTML Best Practices" src='/img/logo.jpg'>

Good:

<img alt="HTML Best Practices" src="/img/logo.jpg">

Don’t separate attributes with two or more white spaces

Your weird formatting rule confuses someone.

Bad:

<input   name="q"  type="search">

Good:

<input name="q" type="search">

Omit boolean attribute value

It’s easy to write, isn’t it?

Bad:

<audio autoplay="autoplay" src="/audio/theme.mp3">

Good:

<audio autoplay src="/audio/theme.mp3">

Omit namespaces

SVG and MathML can be used directly in an HTML document.

Bad:

<svg xmlns="http://www.w3.org/2000/svg">
  ...
</svg>

Good:

<svg>
  ...
</svg>

Don’t use XML attributes

We write an HTML document.

Bad:

<span lang="ja" xml:lang="ja">...</span>

Good:

<span lang="ja">...</span>

Don’t mix `data-*`, Microdata and RDFa Lite attributes with common attributes

A tag string can be very complicated. This simple rule helps reading such tag string.

Bad:

<img alt="HTML Best Practices" data-height="31" data-width="88" itemprop="image" src="/img/logo.png">

Good:

<img alt="HTML Best Practices" src="/img/logo.png" data-width="88" data-height="31" itemprop="image">

Prefer default implicit ARIA semantics

Some element has an ARIA role implicitly in an HTML document, don’t specify it.

Bad:

<nav role="navigation">
  ...
</nav><hr role="separator">

Good:

<nav>
  ...
</nav><hr>

2.The root element

Add `lang` attribute

lang attribute will help to translate an HTML document.

Bad:

<html>

Good:

<html lang="en-US">

Keep `lang` attribute value as short as possible

Japanese is only used in Japan. So the country code is not necessary.

Bad:

<html lang="ja-JP">

Good:

<html lang="ja">

Avoid `data-*` as much as possible

An appropriate attribute can be handled properly by browsers.

Bad:

<span data-language="french">chemises</span>
...
<strong data-type="warning">Do not wash!</strong>

Good:

<span title="French"><span lang="fr-FR">chemises</span></span>
...
<strong class="warning">Do not wash!</strong>

3.Document metadata

Add `title` element

A value for title element is used by various application not only a browser.

Bad:

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

Good:

<head>
  <meta charset="UTF-8">
  <title>HTML Best Practices</title>
</head>

Don’t use `base` element

An absolute path or URL is safer for both developers and users.

Bad:

<head>
  ...
  <base href="/blog/">
  <link href="hello-world" rel="canonical">
  ...
</head>

Good:

<head>
  ...
  <link href="/blog/hello-world" rel="canonical">
  ...
</head>

Specify MIME type of minor linked resources

This is a hint on how the application handles this resource.

Bad:

<link href="/pdf" rel="alternate">
<link href="/feed" rel="alternate">
<link href="/css/screen.css" rel="stylesheet">

Good:

<link href="/pdf" rel="alternate" type="application/pdf">
<link href="/feed" rel="alternate" type="application/rss+xml">
<link href="/css/screen.css" rel="stylesheet">

Don’t link to `favicon.ico`

Almost all browsers fetch /favicon.ico automatically and asynchronously.

Bad:

<link href="/favicon.ico" rel="icon" type="image/vnd.microsoft.icon">

Good:

<!-- Place `favicon.ico` in the root directory. -->

Add `apple-touch-icon` link

A default request path for touch icon was changed suddenly.

Bad:

<!-- Hey Apple! Please download `/apple-touch-icon.png`! -->

Good:

<link href="/apple-touch-icon.png" rel="apple-touch-icon">

Add `title` attribute to alternate stylesheets

A human-readable label helps people selecting proper stylesheet.

Bad:

<link href="/css/screen.css" rel="stylesheet">
<link href="/css/high-contrast.css" rel="alternate stylesheet">

Good:

<link href="/css/screen.css" rel="stylesheet">
<link href="/css/high-contrast.css" rel="alternate stylesheet" title="High contrast">

For URL, use `link` element

A value of href attribute can be resolved as a URL.

Bad:

<section itemscope itemtype="http://schema.org/BlogPosting">
  <meta content="https://example.com/blog/hello" itemprop="url">
  ...
</section>

Good:

<section itemscope itemtype="http://schema.org/BlogPosting">
  <link href="/blog/hello" itemprop="url">
  ...
</section>

Specify document character encoding

UTF-8 is not default in all browsers yet.

Bad:

<head>
  <title>HTML Best Practices</title>
</head>

Good:

<head>
  <meta charset="UTF-8">
  <title>HTML Best Practices</title>
</head>

Don’t use legacy character encoding format

HTTP headers should be specified by a server, be simple.

Bad:

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

Good:

<meta charset="UTF-8">

Specify character encoding at first

Spec requires the character encoding is specified within the first 1024 bytes of the document.

Bad:

<head>
  <meta content="width=device-width" name="viewport">
  <meta charset="UTF-8">
  ...
</head>

Good:

<head>
  <meta charset="UTF-8">
  <meta content="width=device-width" name="viewport">
  ...
</head>

Use UTF-8

With UTF-8, you are free to use Emoji.

Bad:

<meta charset="Shift_JIS">

Good:

<meta charset="UTF-8">

Omit `type` attribute for CSS

In HTML, default type attribute’s value of style element is text/css.

Bad:

<style type="text/css">
  ...
</style>

Good:

<style>
  ...
</style>

Don’t comment out contents of `style` element

This ritual is for the old browser.

Bad:

<style>
<!--
  ...
  -->
</style>

Good:

<style>
  ...
</style>

Don’t mix tag for CSS and JavaScript

Sometimes script element blocks DOM construction.

Bad:

<script src="/js/jquery.min.js"></script>
<link href="/css/screen.css" rel="stylesheet">
<script src="/js/main.js"></script>

Good:

<link href="/css/screen.css" rel="stylesheet">
<script src="/js/jquery.min.js"></script>
<script src="/js/main.js"></script>

Also good:

<script src="/js/jquery.min.js"></script>
<script src="/js/main.js"></script>
<link href="/css/screen.css" rel="stylesheet">

4.Sections

Add `body` element

Sometimes body element is complemented in unexpected position by a browser.

Bad:

<html>
  <head>
    ...
  </head>
  ...
</html>

Good:

<html>
  <head>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Forget about `hgroup` element

This element is not used very much.

Bad:

<hgroup>
  <h1>HTML Best Practices</h1>
  <h2>For writing maintainable and scalable HTML documents.</h2>
</hgroup>

Good:

<h1>HTML Best Practices</h1>
<p>For writing maintainable and scalable HTML documents.</p>

Use `address` element only for contact information

address element is for an email address, social network account, street address, telephone number, or something you can get in touch with.

Bad:

<address>No rights reserved.</address>

Good:

<address>Contact: <a href="https://twitter.com/hail2u_">Kyo Nagashima</a></address>

5. Grouping content

Don’t start with a newline in `pre` element

A first newline will be ignored in the browsers, but second and later are rendered.

Bad:

<pre>
&lt;!DOCTYPE html&gt;
</pre>

Good:

<pre>&lt;!DOCTYPE html&gt;
</pre>

Use appropriate element in `blockquote` element

blockquote element’s content is a quote, not a chunk of characters.

Bad:

<blockquote>For writing maintainable and scalable HTML documents.</blockquote>

Good:

<blockquote>
  <p>For writing maintainable and scalable HTML documents.</p>
</blockquote>

Don’t include attribution directly in `blockquote` element

blockquote element’s content is a quote.

Bad:

<blockquote>
  <p>For writing maintainable and scalable HTML documents.</p>  <p>— HTML Best Practices</p>
</blockquote>

Good:

<blockquote>
  <p>For writing maintainable and scalable HTML documents.</p>
</blockquote><p>— HTML Best Practices</p>

Also good:

<figure>
  <blockquote>
    <p>For writing maintainable and scalable HTML documents.</p>
  </blockquote>  <figcaption>— HTML Best Practices</figcaption>
</figure>

Write one list item per line

Looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong line is hard toooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo read.

Bad:

<ul>
  <li>General</li><li>The root Element</li><li>Sections</li>...
</ul>

Good:

<ul>
  <li>General</li>
  <li>The root Element</li>
  <li>Sections</li>
  ...
</ul>

Use `type` attribute for `ol` element

Sometimes marker referenced by the contents in the near. If you change marker with type attribute, you will be safe to reference.

Bad:

<head>
  <style>
    .toc {
      list-style-type: upper-roman;
    }
  </style>
</head>
<body>
  <ol class="toc">
    <li>General</li>
    <li>The root Element</li>
    <li>Sections</li>
    ...
  </ol>
</body>

Good:

<body>
  <ol type="I">
    <li>General</li>
    <li>The root Element</li>
    <li>Sections</li>
    ...
  </ol>
</body>

Don’t use `dl` for dialogue

dl element is restricted to an association list in HTML.

Bad:

<dl>
  <dt>Costello</dt>
  <dd>Look, you gotta first baseman?</dd>
  <dt>Abbott</dt>
  <dd>Certainly.</dd>
  <dt>Costello</dt>
  <dd>Who’s playing first?</dd>
  <dt>Abbott</dt>
  <dd>That’s right.</dd>
  <dt>Costello becomes exasperated.</dd>
  <dt>Costello</dt>
  <dd>When you pay off the first baseman every month, who gets the money?</dd>
  <dt>Abbott</dt>
  <dd>Every dollar of it.</dd>
</dl>

Good:

<p>Costello: Look, you gotta first baseman?</p>
<p>Abbott: Certainly.</p>
<p>Costello: Who’s playing first?</p>
<p>Abbott: That’s right.</p>
<p>Costello becomes exasperated.</p>
<p>Costello: When you pay off the first baseman every month, who gets the money?</p>
<p>Abbott: Every dollar of it.</p>

Place `figcaption` element as the first or last child of `figure` element

Spec disallows figcaption element in the middle of figure element.

Bad:

<figure>
  <img alt="Front cover of the “HTML Best Practices” book" src="/img/front-cover.png">
  <figcaption>“HTML Best Practices” Cover Art</figcaption>
  <img alt="Back cover of the “HTML Best Practices” book" src="/img/back-cover.png">
</figure>

Good:

<figure>
  <img alt="Front cover of the “HTML Best Practices” book" src="/img/front-cover.png">
  <img alt="Back cover of the “HTML Best Practices” book" src="/img/back-cover.png">
  <figcaption>“HTML Best Practices” Cover Art</figcaption>
</figure>

Use `main` element

main element can be used wrapping contents.

Bad:

<div id="content">
  ...
</div>

Good:

<main>
  ...
</main>

Avoid `div` element as much as possible

div element is an element of last resort.

Bad:

<div class="chapter">
  ...
</div>

Good:

<section>
  ...
</section>

HTML BEST PRACTICES

1.General

Start with DOCTYPE

Don’t use legacy or obsolete DOCTYPE

Don’t use XML Declaration

Don’t use character references as much as possible

Escape &, <, >, ", and ' with named character references

Use numeric character references for control or invisible characters

Put white spaces around comment contents

Don’t omit the closing tag

Don’t mix empty element format

Don’t put white spaces around tags and attribute values

Don’t mix character cases

Don’t mix quotation marks

Don’t separate attributes with two or more white spaces

Omit boolean attribute value

Omit namespaces

Don’t use XML attributes

Don’t mix data-*, Microdata and RDFa Lite attributes with common attributes

Prefer default implicit ARIA semantics

2.The root element

Add lang attribute

Keep lang attribute value as short as possible

Avoid data-* as much as possible

3.Document metadata

Add title element

Don’t use base element

Specify MIME type of minor linked resources

Don’t link to favicon.ico

Add apple-touch-icon link

Add title attribute to alternate stylesheets

For URL, use link element

Specify document character encoding

Don’t use legacy character encoding format

Specify character encoding at first

Use UTF-8

Omit type attribute for CSS

Don’t comment out contents of style element

Don’t mix tag for CSS and JavaScript

4.Sections

Add body element

Forget about hgroup element

Use address element only for contact information

5. Grouping content

Don’t start with a newline in pre element

Use appropriate element in blockquote element

Don’t include attribution directly in blockquote element

Write one list item per line

Use type attribute for ol element

Don’t use dl for dialogue

Place figcaption element as the first or last child of figure element

Use main element

Avoid div element as much as possible

Written by Ramin Mammadzada

Escape `&`, `<`, `>`, `"`, and `'` with named character references

Don’t mix `data-*`, Microdata and RDFa Lite attributes with common attributes

Add `lang` attribute

Keep `lang` attribute value as short as possible

Avoid `data-*` as much as possible

Add `title` element

Don’t use `base` element

Don’t link to `favicon.ico`

Add `apple-touch-icon` link

Add `title` attribute to alternate stylesheets

For URL, use `link` element

Omit `type` attribute for CSS

Don’t comment out contents of `style` element

Add `body` element

Forget about `hgroup` element

Use `address` element only for contact information

Don’t start with a newline in `pre` element

Use appropriate element in `blockquote` element

Don’t include attribution directly in `blockquote` element

Use `type` attribute for `ol` element

Don’t use `dl` for dialogue

Place `figcaption` element as the first or last child of `figure` element

Use `main` element

Avoid `div` element as much as possible