Skip to content
Permalink
Newer
Older
100755 205 lines (148 sloc) 9.33 KB
Jan 28, 2020
1
[HTML5 Boilerplate homepage](https://html5boilerplate.com/) | [Documentation
2
table of contents](TOC.md)
3
4
# The HTML
5
6
By default, HTML5 Boilerplate provides two `html` pages:
7
8
* [`index.html`](#indexhtml) - a default HTML skeleton that should form the
9
basis of all pages on your website
10
* `404.html` - a placeholder 404 error page
11
12
13
## `index.html`
14
15
16
### The `no-js` Class
17
18
The `no-js` class is provided in order to allow you to more easily and
19
explicitly add custom styles based on whether JavaScript is disabled
20
(`.no-js`) or enabled (`.js`). Using this technique also helps [avoid the
21
FOUC](https://www.paulirish.com/2009/avoiding-the-fouc-v3/).
22
23
24
## Language Attribute
25
26
Please consider specifying the language of your content by adding a [value](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) to the `lang`
27
attribute in the `<html>` as in this example:
28
29
```html
30
<html class="no-js" lang="en">
31
```
32
33
### The order of the `<title>` and `<meta>` tags
34
35
The charset declaration (`<meta charset="utf-8">`) must be included completely
36
within the [first 1024 bytes of the document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
37
and should be specified as early as possible (before any content that could
38
be controlled by an attacker, such as a `<title>` element) in order to avoid a
39
potential [encoding-related security issue](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
40
in Internet Explorer
41
42
## Meta Description
43
44
The `description` meta tag provides a short description of the page.
45
In some situations this description is used as a part of the snippet
46
shown in the search results.
47
48
```html
49
<meta name="description" content="This is a description">
50
```
51
52
Google's [Create good meta descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
53
documentation has useful tips on creating an effective description.
54
55
## Mobile Viewport
56
57
There are a few different options that you can use with the [`viewport` meta
58
tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4 "Viewport and
59
Media Queries - The Complete Idiot's Guide"). You can find out more in [the
60
MDN Web Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag).
61
HTML5 Boilerplate comes with a simple setup that strikes a good balance for general use cases.
62
63
```html
64
<meta name="viewport" content="width=device-width, initial-scale=1">
65
```
66
67
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you can do
68
so with additional viewport parameters. [Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
69
for details.
70
71
## Web App Manifest
72
73
HTML5 Boilerplate includes a simple web app manifest file.
74
75
The web app manifest is a simple JSON file that allows you to control how your
76
app appears on a device's home screen, what it looks like when it launches
77
in that context and what happens when it is launched. This allows for much greater
78
control over the UI of a saved site or web app on a mobile device.
79
80
It's linked to from the HTML as follows:
81
82
```html
83
<link rel="manifest" href="site.webmanifest">
84
```
85
Our [site.webmanifest](https://github.com/h5bp/html5-boilerplate/blob/master/src/site.webmanifest) contains a very skeletal "app" definition, just to show the basic usage.
86
You should fill this file out with [more information about your site or application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
87
88
## Favicons and Touch Icon
89
90
The shortcut icons should be put in the root directory of your site. `favicon.ico`
91
is automatically picked up by browsers if it's placed in the root. HTML5
92
Boilerplate comes with a default set of icons (include favicon and one Apple
93
Touch Icon) that you can use as a baseline to create your own.
94
95
Please refer to the more detailed description in the [Extend section](extend.md)
96
of these docs.
97
98
## The Content Area
99
100
The central part of the boilerplate template is pretty much empty. This is
101
intentional, in order to make the boilerplate suitable for both web page and
102
web app development.
103
104
### Browser Upgrade Prompt
105
106
The main content area of the boilerplate includes a prompt to install an up to
107
date browser for users of IE 9 and lower. If you intended to support IE, then you
108
should edit or remove the snippet of code.
109
110
## Modernizr
111
112
HTML5 Boilerplate uses a custom build of Modernizr.
113
114
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes to
115
the `html` element based on the results of feature test and which ensures that
116
all browsers can make use of HTML5 elements (as it includes the HTML5 Shiv).
117
This allows you to target parts of your CSS and JavaScript based on the
118
features supported by a browser.
119
120
Starting with version 3 Modernizr can be customized using the [modernizr-config.json](https://github.com/h5bp/html5-boilerplate/blob/master/modernizr-config.json) and the
121
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).
122
123
## What About Polyfills?
124
125
If you need to include [polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill)
126
in your project, you must make sure those load before any other JavaScript. If you're
127
using a polyfill CDN service, like [cdn.polyfill.io](https://cdn.polyfill.io/),
128
just put it before the other scripts in the bottom of the page:
129
130
```html
131
<script src="js/vendor/modernizr-3.8.0.min.js"></script>
132
<script src="https://cdn.polyfill.io/v3/polyfill.min.js"></script>
133
<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
134
<script>window.jQuery || document.write('<script src="js/vendor/jquery-3.4.1.min.js"><\/script>')</script>
135
<script src="js/plugins.js"></script>
136
<script src="js/main.js"></script>
137
</body>
138
```
139
140
If you like to just include the polyfills yourself, you could include them in
141
`js/plugins.js`. When you have a bunch of polyfills to load in, you could
142
also create a `polyfills.js` file in the `js/vendor` directory or include the files
143
individually and combine them using a build tool. Always ensure that the polyfills
144
are all loaded before any other JavaScript.
145
146
There are some misconceptions about Modernizr and polyfills. It's important
147
to understand that Modernizr just handles feature checking, not polyfilling
148
itself. The only thing Modernizr does regarding polyfills is that the team
149
maintains [a huge list of cross Browser polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
150
151
### jQuery CDN for jQuery
152
153
The jQuery CDN version of the jQuery JavaScript library is referenced towards
154
the bottom of the page. A local fallback of jQuery is included for rare instances
155
when the CDN version might not be available, and to facilitate offline
156
development.
157
158
The jQuery CDN version was chosen over other potential candidates
159
([like Google's Hosted Libraries](https://developers.google.com/speed/libraries/))
160
because it's fast ([comparable or faster than Google by some
161
measures](https://www.cdnperf.com/#jsdelivr,cdnjs,google,yandex,microsoft,jquery,bootstrapcdn/https/90))
162
and, (unlike Google's CDN) is available to China's hundreds of millions of internet users.
163
For many years we [chose](https://github.com/h5bp/html5-boilerplate/issues/1191)
164
the Google Hosted version over the jQuery CDN because it was available
165
over HTTPS (the jQuery CDN was not,) and it offered a better chance of
166
hitting the cache lottery owing to the popularity of the Google CDN.
167
The first issue is no longer valid and the second is far outweighed by
168
being able to serve jQuery to users in China.
169
170
While the jQuery CDN is a strong default solution your site or application may
171
require a different configuration. Testing your site with services like
172
[WebPageTest](https://www.webpagetest.org/) and browser tools like
173
[PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) will help you examine the real
174
world performance of your site and can show where you can optimize your specific
175
site or application.
176
177
### Google Universal Analytics Tracking Code
178
179
Finally, an optimized version of the Google Universal Analytics tracking code is
180
included.
181
182
We use `analytics.js` rather than the newer `gtag.js` as
183
[it's faster and supports tasks and plugins](https://github.com/philipwalton/analyticsjs-boilerplate/issues/19#issuecomment-333714370)
184
185
The beacon transport mechanism is used to send all hits [which saves HTTP requests and improves performance](https://philipwalton.com/articles/the-google-analytics-setup-i-use-on-every-site-i-build/#loading-analytics.js).
186
187
Google recommends that this script be placed at the top of the page.
188
Factors to consider: if you place this script at the top of the page, you’ll
189
be able to count users who don’t fully load the page, and you’ll incur the max
190
number of simultaneous connections of the browser.
191
192
Further information:
193
194
- [Introduction to
195
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
196
- [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
197
198
**N.B.** The Google Analytics snippet is included by default mainly
199
because Google Analytics is [currently one of the most popular tracking
200
solutions](https://trends.builtwith.com/analytics/Google-Analytics) out there.
201
However, its usage isn't set in stone, and you SHOULD consider exploring the
202
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software)
203
and use whatever suits your needs best.
204
205
You can’t perform that action at this time.