Skip to content
/ html-best-practices Public

For writing maintainable and scalable HTML documents

4.1k stars 439 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

hail2u/html-best-practices

BranchesTags

Repository files navigation

Translations: English · বাংলা · Dansk · Deutsch · Español · فارسی · Français · Indonesia · 日本語 · 한국어 · Português (BR) · Română · Русский · Türkçe · Українська · Tiếng Việt · 简体中文 · 正體中文

HTML Best Practices

For writing maintainable and scalable HTML documents

General

Start with DOCTYPE

DOCTYPE is required for activating no-quirks 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 characters 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 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 a 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 a 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 elements have an ARIA role implicitly in an HTML document, don’t specify them.

Bad:

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

<hr role="separator">

Good:

<nav>
  ...
</nav>

<hr>

The root element

Add lang attribute

lang attribute will help translating 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 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">chemises</span></span>
...
<strong class="warning">Do not wash!</strong>

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 how 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 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">

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 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>

Grouping content

Don’t start with newline in pre element

A first newline will 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 chunks 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 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>

Text-level semantics

Don’t split same link that can be grouped

a element can wrap almost all elements (except interactive elements like form controls and a element itself).

Bad:

<h1><a href="https://whatwg.org/">WHATWG</a></h1>

<p><a href="https://whatwg.org/">A community maintaining and evolving HTML since 2004.</a></p>

Good:

<a href="https://whatwg.org/">
  <h1>WHATWG</h1>

  <p>A community maintaining and evolving HTML since 2004.</p>
</a>

Use download attribute for downloading a resource

It will force browsers to download linked resource to the storage.

Bad:

<a href="/downloads/offline.zip">offline version</a>

Good:

<a download href="/downloads/offline.zip">offline version</a>

Use rel, hreflang, and type attribute if needed

These hints help applications to handle linked resources.

Bad:

<a href="/ja/pdf">Japanese PDF version</a>

Good:

<a href="/ja/pdf" hreflang="ja" rel="alternate" type="application/pdf">Japanese PDF version</a>

Clear link text

Link text should be the label of its linked resource.

Bad:

<p><a href="/pdf" rel="alternate" type="application/pdf">Click here</a> to view PDF version.</p>

Good:

<p><a href="/pdf" rel="alternate" type="application/pdf">PDF version</a> is also available.</p>

Don’t use em element for warning or caution

These are seriousness. So, strong element is more appropriate.

Bad:

<em>Caution!</em>

Good:

<strong>Caution!</strong>

Avoid s, i, b, and u element as much as possible

These elements’ semantics is too difficult to humans.

Bad:

<i class="icon-search"></i>

Good:

<span class="icon-search" aria-hidden="true"></span>

Don’t put quotes to q element

Quotes are provided by the browser.

Bad:

<q>“For writing maintainable and scalable HTML documents”</q>

Good:

<q>For writing maintainable and scalable HTML documents</q>

Also good:

“For writing maintainable and scalable HTML documents”

Add title attribute to abbr element

There is no other way to represent its expansion.

Bad:

<abbr>HBP</abbr>

Good:

<abbr title="HTML Best Practices">HBP</abbr>

Markup ruby element verbosely

ruby element support is not completed across the modern browsers.

Bad:

<ruby>HTML<rt>えいちてぃーえむえる</ruby>

Good:

<ruby>HTML<rp> (</rp><rt>えいちてぃーえむえる</rt><rp>) </rp></ruby>

Add datetime attribute to non-machine-readable time element

When datetime attribute does not present, the format of time element’s content is restricted.

Bad:

<time>Dec 19, 2014</time>

Good:

<time datetime="2014-12-19">Dec 19, 2014</time>

Specify code language with class attribute prefixed with language-

This is not a formal way, but spec mentions this.

Bad:

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

Good:

<code class="language-html">&lt;!DOCTYPE html&gt;</code>

Keep kbd element as simple as possible

Nesting kbd element is too difficult to humans.

Bad:

<kbd><kbd>Ctrl</kbd>+<kbd>F5</kbd></kbd>

Good:

<kbd>Ctrl+F5</kbd>

Avoid span element as much as possible

span element is an element of last resort.

Bad:

HTML <span class="best">Best</span> Practices

Good:

HTML <em>Best</em> Practices

Break after br element

Line break should be needed where br element is used.

Bad:

<p>HTML<br>Best<br>Practices</p>

Good:

<p>HTML<br>
Best<br>
Practices</p>

Don’t use br element only for presentational purpose

br element is not for line breaking, it is for line breaks in the contents.

Bad:

<p><label>Rule name: <input name="rule-name" type="text"></label><br>
<label>Rule description:<br>
<textarea name="rule-description"></textarea></label></p>

Good:

<p><label>Rule name: <input name="rule-name" type="text"></label></p>
<p><label>Rule description:<br>
<textarea name="rule-description"></textarea></label></p>

Edits

Don’t stride ins and del element over other elements

Elements cannot overflow other elements.

Bad:

<p>For writing maintainable and scalable HTML documents.<del> And for mental stability.</p>

<p>Don’t trust!</p></del>

Good:

<p>For writing maintainable and scalable HTML documents.<del> And for mental stability.</del></p>

<del><p>Don’t trust!</p></del>

Embedded content

Provide fallback img element for picture element

The support of picture element is not good yet.

Bad:

<picture>
  <source srcset="/img/logo.webp" type="image/webp">
  <source srcset="/img/logo.hdp" type="image/vnd.ms-photo">
  <source srcset="/img/logo.jp2" type="image/jp2">
  <source srcset="/img/logo.jpg" type="image/jpg">
</picture>

Good:

<picture>
  <source srcset="/img/logo.webp" type="image/webp">
  <source srcset="/img/logo.hdp" type="image/vnd.ms-photo">
  <source srcset="/img/logo.jp2" type="image/jp2">
  <img src="/img/logo.jpg">
</picture>

Add alt attrbute to img element if needed

alt attribute helps those who cannot process images or have image loading disabled.

Bad:

<img src="/img/logo.png">

Good:

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

Empty alt attribute if possible

If the image is supplemental, there is equivalent content somewhere in the near.

Bad:

<img alt="Question mark icon" src="/img/icon/help.png"> Help

Good:

<img alt="" src="/img/icon/help.png"> Help

Omit alt attribute if possible

Sometimes you don’t know what text is suitable for alt attribute.

Bad:

<img alt="CAPTCHA" src="captcha.cgi?id=82174">

Good:

<img src="captcha.cgi?id=82174" title="CAPTCHA">
(If you cannot see the image, you can use an <a href="?audio">audio</a> test instead.)

Empty iframe element

There is some restriction in its content. Being empty is always safe.

Bad:

<iframe src="/ads/default.html">
  <p>If your browser support inline frame, ads are displayed here.</p>
</iframe>

Good:

<iframe src="/ads/default.html"></iframe>

Markup map element content

This content presents to a screen reader.

Bad:

<map name="toc">
  <a href="#general">General</a>
  <area alt="General" coords="0, 0, 40, 40" href="#General"> |
  <a href="#the_root_element">The root element</a>
  <area alt="The root element" coords="50, 0, 90, 40" href="#the_root_element"> |
  <a href="#sections">Sections</a>
  <area alt="Sections" coords="100, 0, 140, 40" href="#sections">
</map>

Good:

<map name="toc">
  <p>
    <a href="#general">General</a>
    <area alt="General" coords="0, 0, 40, 40" href="#General"> |
    <a href="#the_root_element">The root element</a>
    <area alt="The root element" coords="50, 0, 90, 40" href="#the_root_element"> |
    <a href="#sections">Sections</a>
    <area alt="Sections" coords="100, 0, 140, 40" href="#sections">
  </p>
</map>

Provide fallback content for audio or video element

Fallback content is needed for newly introduced elements in HTML.

Bad:

<video>
  <source src="/mov/theme.mp4" type="video/mp4">
  <source src="/mov/theme.ogv" type="video/ogg">
  ...
</video>

Good:

<video>
  <source src="/mov/theme.mp4" type="video/mp4">
  <source src="/mov/theme.ogv" type="video/ogg">
  ...
  <iframe src="//www.youtube.com/embed/..." allowfullscreen></iframe>
</video>

Tabular data

Write one cell per line

Long lines are hard to scan.

Bad:

<tr>
  <td>General</td><td>The root Element</td><td>Sections</td>
</tr>

Good:

<tr>
  <td>General</td>
  <td>The root Element</td>
  <td>Sections</td>
</tr>

Use th element for header cell

There is no reason to avoid this.

Bad:

<table>
  <thead>
    <tr>
      <td><strong>Element</strong></td>
      <td><strong>Empty</strong></td>
      <td><strong>Tag omission</strong></td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong><code>pre</code></strong></td>
      <td>No</td>
      <td>Neither tag is omissible</td>
    </tr>
    <tr>
      <td><strong><code>img</code></strong></td>
      <td>Yes</td>
      <td>No end tag</td>
    </tr>
  </tbody>
</table>

Good:

<table>
  <thead>
    <tr>
      <th>Element</th>
      <th>Empty</th>
      <th>Tag omission</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th><code>pre</code></th>
      <td>No</td>
      <td>Neither tag is omissible</td>
    </tr>
    <tr>
      <th><code>img</code></th>
      <td>Yes</td>
      <td>No end tag</td>
    </tr>
  </tbody>
</table>

Forms

Wrap form control with label element

label element helps focusing form element.

Bad:

<p>Query: <input name="q" type="text"></p>

Good:

<p><label>Query: <input name="q" type="text"></label></p>

Omit for attribute if possible

label element can contain some form elements.

Bad:

<label for="q">Query: </label><input id="q" name="q" type="text">

Good:

<label>Query: <input name="q" type="text"></label>

Use appropriate type attribute for input element

With appropriate type, a browser gives tiny features to the input element.

Bad:

<label>Search keyword: <input name="q" type="text"></label>

Good:

<label>Search keyword: <input name="q" type="search"></label>

Add value attribute to input type="submit"

The default label for submit button is not standarized across the browser and languages.

Bad:

<input type="submit">

Good:

<input type="submit" value="Search">

Add title attribute to input element when there is pattern attribute

If input text does not match to pattern attribute, the value of title attribute will be display as a hint.

Bad:

<input name="security-code" pattern="[0-9]{3}" type="text">

Good:

<input name="security-code" pattern="[0-9]{3}" title="A security code is a number in three figures." type="text">

Don’t use placeholder attribute for labeling

label element is for a label, placeholder attribute is for a short hint.

Bad:

<input name="email" placeholder="Email" type="text">

Good:

<label>Email: <input name="email" placeholder="[email protected]" type="text"></label>

Write one option element per line

Long lines are hard to scan.

Bad:

<datalist id="toc">
  <option label="General"><option label="The root element"><option label="Sections">
</datalist>

Good:

<datalist id="toc">
  <option label="General">
  <option label="The root element">
  <option label="Sections">
</datalist>

Add max attribute to progress element

With max attribute, the value attribute can be written in an easy format.

Bad:

<progress value="0.5"> 50%</progress>

Good:

<progress max="100" value="50"> 50%</progress>

Add min and max attribute to meter element

With min and max attribute, the value attribute can be written in an easy format.

Bad:

<meter value="0.5"> 512GB used (1024GB total)</meter>

Good:

<meter min="0" max="1024" value="512"> 512GB used (1024GB total)</meter>

Place legend element as the first child of fieldset element

Spec requires this.

Bad:

<fieldset>
  <p><label>Is this section useful?: <input name="usefulness-general" type="checkbox"></label></p>
  ...
  <legend>About "General"</legend>
</fieldset>

Good:

<fieldset>
  <legend>About "General"</legend>
  <p><label>Is this section useful?: <input name="usefulness-general" type="checkbox"></label></p>
  ...
</fieldset>

Scripting

Omit type attribute for JavaScript

In HTML, the default type attribute’s value of script element is text/javascript.

Bad:

<script type="text/javascript">
  ...
</script>

Good:

<script>
  ...
</script>

Don’t comment out contents of script element

This ritual is for the old browser.

Bad:

<script>
/*<![CDATA[*/
  ...
/*]]>*/
</script>

Also bad:

<script>
<!--
  ...
// -->
</script>

Good:

<script>
  ...
</script>

Don’t use script-injected script element

async attribute is the best for both simplicity and performance.

Bad:

<script>
  var script = document.createElement("script");
  script.async = true;
  script.src = "//example.com/widget.js";
  document.getElementsByTagName("head")[0].appendChild(script);
</script>

Good:

<script async defer src="https://example.com/widget.js"></script>

Other

Indent consistently

Indentation is important for readability.

Bad:

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

Good:

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

Use absolute path for internal links

An absolute path works better on your localhost without internet connection.

Bad:

<link rel="apple-touch-icon" href="http://you.example.com/apple-touch-icon-precomposed.png">
...
<p>You can find more at <a href="//you.example.com/contact.html">contact page</a>.</p>

Good:

<link rel="apple-touch-icon" href="/apple-touch-icon-precomposed.png">
...
<p>You can find more at <a href="/contact.html">contact page</a>.</p>

Don’t use protocol-relative URL for external resources

With protocol, you can load external resources reliably and safely.

Bad:

<script src="//example.com/js/library.js">

Good:

<script src="https://example.com/js/library.js">

Contributors

Translators

License

CC0

About

For writing maintainable and scalable HTML documents

Resources

Readme
Activity

Stars

4.1k stars

Watchers

94 watching

Forks

439 forks
Report repository

Releases

1 tags

Packages

No packages published

Contributors 36

+ 22 contributors