Docs: Make minor improvments in html.md

h5bp · Jul 19, 2014 · 973b845 · 973b845
1 parent 4fca586
commit 973b845
Showing 1 changed file with 35 additions and 16 deletions.
diff --git a/doc/html.md b/doc/html.md
@@ -3,12 +3,24 @@ table of contents](TOC.md)
 
 # The HTML
 
-## The `no-js` class
+By default, HTML5 Boilerplate provides two `html` pages:
 
-Allows you to more easily explicitly add custom styles when JavaScript is
-disabled (`no-js`) or enabled (`js`). More here: [Avoiding the
+* [`index.html`](#indexhtml) - a default HTML skeleton that should form the
+  basis of all pages on your website
+* [`404.html`](#404html) - a placeholder 404 error page
+
+
+## `index.html`
+
+
+### The `no-js` class
+
+The `no-js` class is provided in order to allow you to more easily and
+explicitly add custom styles based on whether JavaScript is disabled
+(`.no-js`) or enabled (`.js`). Using this technique also helps [avoid the
 FOUC](http://paulirish.com/2009/avoiding-the-fouc-v3/).
 
+
 ## Language attribute
 
 Please consider specifying the language of your content by adding the `lang`
@@ -18,22 +30,29 @@ attribute to `<html>` as in this example:
 <html class="no-js" lang="en">
 ```
 
-## The order of meta tags, and `<title>`
+### The order of the `<title>` and `<meta>` tags
+
+The order in which the `<title>` and the `<meta>` tags are specified is
+important because:
+
+1) the charset declaration (`<meta charset="utf-8">`):
+
+   * must be included completely within the [first 1024 bytes of the
+     document](http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
+
+   * should be specified as early as possbile (before any content that could
+     be controlled by an attacker, such as a `<title>` element) in order to
+     avoid a potential [encoding-related security
+     issue](http://code.google.com/p/doctype-mirror/wiki/ArticleUtf7) in
+     Internet Explorer
 
-As recommended by [the HTML5
-spec](http://www.whatwg.org/specs/web-apps/current-work/complete/semantics.html#charset)
-(4.2.5.5 Specifying the document's character encoding), add your charset
-declaration early (before any ASCII art ;) to avoid a potential
-[encoding-related security
-issue](http://code.google.com/p/doctype-mirror/wiki/ArticleUtf7) in IE. It
-should come in the first [1024
-bytes](http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset).
+2) the meta tag for compatibility mode
+   (`<meta http-equiv="X-UA-Compatible" content="IE=edge">`):
 
-The charset should also come before the `<title>` tag, due to [potential XSS
-vectors](http://code.google.com/p/doctype-mirror/wiki/ArticleUtf7).
+   * [needs to be included before all other tags except for the `<title>` and
+     the other `<meta>`
+     tags](http://msdn.microsoft.com/en-us/library/cc288325.aspx)
 
-The meta tag for compatibility mode [needs to be before all elements except
-title and meta](http://h5bp.com/f "Defining Document Compatibility - MSDN").
 
 ## X-UA-Compatible