github/html5-boilerplate
1
1
Fork 0
mirror of https://github.com/h5bp/html5-boilerplate.git synced 2026-01-09 14:48:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

Fixed line lengths

Browse Source
This commit is contained in:
Rob Larsen
2020-04-17 08:05:59 -04:00
parent 274bab1cf4
commit e006c01033
14 changed files with 520 additions and 434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
dist/doc/TOC.md vendored
View File

@@ -14,21 +14,23 @@
## Development
* [Extending and customizing HTML5 Boilerplate](extend.md) — Going further
with the boilerplate.
* [Extending and customizing HTML5 Boilerplate](extend.md) — Going further with
the boilerplate.
## Related projects
The [H5BP organization](https://github.com/h5bp) maintains several projects
that complement HTML5 Boilerplate, projects that can help you improve different
The [H5BP organization](https://github.com/h5bp) maintains several projects that
complement HTML5 Boilerplate, projects that can help you improve different
aspects of your website/web app (e.g.: the performance, security, etc.).
* [Server Configs](https://github.com/h5bp/server-configs) — Fast and
smart configurations for web servers such as Apache and Nginx.
* [Server Configs](https://github.com/h5bp/server-configs) — Fast and smart
configurations for web servers such as Apache and Nginx.
* [Apache](https://github.com/h5bp/server-configs-apache)
* [Google App Engine (GAE)](https://github.com/h5bp/server-configs-gae)
* [Internet Information Services (IIS)](https://github.com/h5bp/server-configs-iis)
* [Internet Information Services
(IIS)](https://github.com/h5bp/server-configs-iis)
* [lighttpd](https://github.com/h5bp/server-configs-lighttpd)
* [Nginx](https://github.com/h5bp/server-configs-nginx)
* [Node.js](https://github.com/h5bp/server-configs-node)
* [Front-end Developer Interview Questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions)
* [Front-end Developer Interview
Questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions)

19
dist/doc/css.md vendored
View File

@@ -8,17 +8,17 @@ HTML5 Boilerplate's CSS includes:
* [Normalize.css](#normalizecss)
* [main.css](#maincss)
This starting CSS does not rely on the presence of
[conditional class names](https://www.paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/),
This starting CSS does not rely on the presence of [conditional class
names](https://www.paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/),
or [Modernizr](https://modernizr.com/), and it is ready to use no matter what
your development preferences happen to be.
## Normalize.css
In order to make browsers render all elements more consistently and in line
with modern standards, we include Normalize.css — a modern, HTML5-ready
alternative to CSS resets.
In order to make browsers render all elements more consistently and in line with
modern standards, we include Normalize.css — a modern, HTML5-ready alternative
to CSS resets.
As opposed to CSS resets, Normalize.css:
@@ -35,8 +35,7 @@ page](https://necolas.github.io/normalize.css/).
## main.css
Several base styles are included that build upon `Normalize.css`. These
styles:
Several base styles are included that build upon `Normalize.css`. These styles:
* provide basic typography settings that improve text readability
* protect against unwanted `text-shadow` during text highlighting
@@ -45,4 +44,8 @@ styles:
* style the prompt that is displayed to users using an outdated browser
* and more...
These styles are included in [main.css](https://github.com/h5bp/html5-boilerplate/blob/master/dist/css/main.css). See the [main.css](https://github.com/h5bp/main.css) project [documentation](https://github.com/h5bp/main.css/blob/master/README.md#features) for a full discussion of these styles.
These styles are included in
[main.css](https://github.com/h5bp/html5-boilerplate/blob/master/dist/css/main.css).
See the [main.css](https://github.com/h5bp/main.css) project
[documentation](https://github.com/h5bp/main.css/blob/master/README.md#features)
for a full discussion of these styles.

198
dist/doc/extend.md vendored
View File

@@ -4,8 +4,8 @@ table of contents](TOC.md)
# Extend and customise HTML5 Boilerplate
Here is some useful advice for how you can make your project with HTML5
Boilerplate even better. We don't want to include it all by default, as
not everything fits with everyone's needs.
Boilerplate even better. We don't want to include it all by default, as not
everything fits with everyone's needs.
* [App Stores](#app-stores)
@@ -24,8 +24,11 @@ not everything fits with everyone's needs.
### Smart App Banners in iOS 6+ Safari
Stop bothering everyone with gross modals advertising your entry in the
App Store. Including the following [meta tag](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html) will unobtrusively give the user the option to download your iOS app, or open it with some data about the user's current state on the website.
Stop bothering everyone with gross modals advertising your entry in the App
Store. Including the following [meta
tag](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html)
will unobtrusively give the user the option to download your iOS app, or open it
with some data about the user's current state on the website.
```html
<meta name="apple-itunes-app" content="app-id=APP_ID,app-argument=SOME_TEXT">
@@ -35,18 +38,17 @@ App Store. Including the following [meta tag](https://developer.apple.com/librar
In short, DNS Prefetching is a method of informing the browser of domain names
referenced on a site so that the client can resolve the DNS for those hosts,
cache them, and when it comes time to use them, have a faster turn around on
the request.
cache them, and when it comes time to use them, have a faster turn around on the
request.
### Implicit prefetches
There is a lot of prefetching done for you automatically by the browser. When
the browser encounters an anchor in your html that does not share the same
domain name as the current location the browser requests, from the client OS,
the IP address for this new domain. The client first checks its cache and
then, lacking a cached copy, makes a request from a DNS server. These requests
happen in the background and are not meant to block the rendering of the
page.
the IP address for this new domain. The client first checks its cache and then,
lacking a cached copy, makes a request from a DNS server. These requests happen
in the background and are not meant to block the rendering of the page.
The goal of this is that when the foreign IP address is finally needed it will
already be in the client cache and will not block the loading of the foreign
@@ -68,9 +70,9 @@ FOREIGN DOMAINS.
### Explicit prefetches
Typically the browser only scans the HTML for foreign domains. If you have
resources that are outside of your HTML (a javascript request to a remote
server or a CDN that hosts content that may not be present on every page of
your site, for example) then you can queue up a domain name to be prefetched.
resources that are outside of your HTML (a javascript request to a remote server
or a CDN that hosts content that may not be present on every page of your site,
for example) then you can queue up a domain name to be prefetched.
```html
<link rel="dns-prefetch" href="//example.com">
@@ -80,8 +82,8 @@ your site, for example) then you can queue up a domain name to be prefetched.
You can use as many of these as you need, but it's best if they are all
immediately after the [Meta
Charset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-charset)
element (which should go right at the top of the `head`), so the browser can
act on them ASAP.
element (which should go right at the top of the `head`), so the browser can act
on them ASAP.
#### Common Prefetch Links
@@ -126,7 +128,9 @@ ga('create', 'UA-XXXXX-X', 'auto'); ga('send', 'pageview');
To customize further, see Google's [Advanced
Setup](https://developers.google.com/analytics/devguides/collection/analyticsjs/),
[Pageview](https://developers.google.com/analytics/devguides/collection/analyticsjs/pages),
and [Event](https://developers.google.com/analytics/devguides/collection/analyticsjs/events) Docs.
and
[Event](https://developers.google.com/analytics/devguides/collection/analyticsjs/events)
Docs.
### Track jQuery AJAX requests in Google Analytics
@@ -204,7 +208,8 @@ $(function(){
Enabling your application for pinning will allow IE users to add it to their
Windows Taskbar and Start Menu. This comes with a range of new tools that you
can easily configure with the elements below. See more [documentation on IE
Pinned Sites](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/samples/gg491731(v%3dvs.85)).
Pinned
Sites](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/samples/gg491731(v%3dvs.85)).
### Name the Pinned Site for Windows
@@ -238,8 +243,8 @@ track the number of pinned users, like so:
### Recolor IE's controls manually for a Pinned Site
IE will automatically use the overall color of your Pinned Site's favicon to
shade its browser buttons. UNLESS you give it another color here. Only use
named colors (`red`) or hex colors (`#ff0000`).
shade its browser buttons. UNLESS you give it another color here. Only use named
colors (`red`) or hex colors (`#ff0000`).
```html
<meta name="msapplication-navbutton-color" content="#ff0000">
@@ -248,8 +253,7 @@ named colors (`red`) or hex colors (`#ff0000`).
### Manually set the window size of a Pinned Site
If the site should open at a certain window size once pinned, you can specify
the dimensions here. It only supports static pixel dimensions. 800x600
minimum.
the dimensions here. It only supports static pixel dimensions. 800x600 minimum.
```html
<meta name="msapplication-window" content="width=800;height=600">
@@ -259,8 +263,7 @@ minimum.
Add Jump List Tasks that will appear when the Pinned Site's icon gets a
right-click. Each Task goes to the specified URL, and gets its own mini icon
(essentially a favicon, a 16x16 .ICO). You can add as many of these as you
need.
(essentially a favicon, a 16x16 .ICO). You can add as many of these as you need.
```html
<meta name="msapplication-task" content="name=Task 1;action-uri=http://host/Page1.html;icon-uri=http://host/icon1.ico">
@@ -273,22 +276,24 @@ Windows 8 adds the ability for you to provide a PNG tile image and specify the
tile's background color. [Full details on the IE
blog](https://blogs.msdn.microsoft.com/ie/2012/06/08/high-quality-visuals-for-pinned-sites-in-windows-8/).
* Create a 144x144 image of your site icon, filling all of the canvas, and
using a transparent background.
* Save this image as a 32-bit PNG and optimize it without reducing
colour-depth. It can be named whatever you want (e.g. `metro-tile.png`).
* To reference the tile and its color, add the HTML `meta` elements described
in the IE Blog post.
* Create a 144x144 image of your site icon, filling all of the canvas, and using
a transparent background.
* Save this image as a 32-bit PNG and optimize it without reducing colour-depth.
It can be named whatever you want (e.g. `metro-tile.png`).
* To reference the tile and its color, add the HTML `meta` elements described in
the IE Blog post.
### (Windows 8) Badges for Pinned Sites
IE will poll an XML document for badge information to display on your app's
tile in the Start screen. The user will be able to receive these badge updates
even when your app isn't actively running. The badge's value can be a number,
or one of a predefined list of glyphs.
IE will poll an XML document for badge information to display on your app's tile
in the Start screen. The user will be able to receive these badge updates even
when your app isn't actively running. The badge's value can be a number, or one
of a predefined list of glyphs.
* [Tutorial on IEBlog with link to badge XML schema](https://blogs.msdn.microsoft.com/ie/2012/04/03/pinned-sites-in-windows-8/)
* [Available badge values](https://docs.microsoft.com/en-us/uwp/schemas/tiles/badgeschema/element-badge)
* [Tutorial on IEBlog with link to badge XML
schema](https://blogs.msdn.microsoft.com/ie/2012/04/03/pinned-sites-in-windows-8/)
* [Available badge
values](https://docs.microsoft.com/en-us/uwp/schemas/tiles/badgeschema/element-badge)
```html
<meta name="msapplication-badge" value="frequency=NUMBER_IN_MINUTES;polling-uri=https://www.example.com/path/to/file.xml">
@@ -296,16 +301,18 @@ or one of a predefined list of glyphs.
### Disable link highlighting upon tap in IE10
Similar to [-webkit-tap-highlight-color](https://davidwalsh.name/mobile-highlight-color)
in iOS Safari. Unlike that CSS property, this is an HTML meta element, and its
Similar to
[-webkit-tap-highlight-color](https://davidwalsh.name/mobile-highlight-color) in
iOS Safari. Unlike that CSS property, this is an HTML meta element, and its
value is boolean rather than a color. It's all or nothing.
```html
<meta name="msapplication-tap-highlight" content="no" />
```
You can read about this useful element and more techniques in
[Microsoft's documentation on adapting WebKit-oriented apps for IE10](https://blogs.windows.com/buildingapps/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10/)
You can read about this useful element and more techniques in [Microsoft's
documentation on adapting WebKit-oriented apps for
IE10](https://blogs.windows.com/buildingapps/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10/)
## Search
@@ -317,9 +324,8 @@ Submit it to search engine tool:
* [Google](https://www.google.com/webmasters/tools/sitemap-list)
* [Bing](https://www.bing.com/toolbox/webmaster)
* [Yandex](https://webmaster.yandex.com/)
* [Baidu](https://zhanzhang.baidu.com/)
OR
Insert the following line anywhere in your robots.txt file, specifying the path to your sitemap:
* [Baidu](https://zhanzhang.baidu.com/) OR Insert the following line anywhere in
your robots.txt file, specifying the path to your sitemap:
```
Sitemap: https://example.com/sitemap_location.xml
```
@@ -350,7 +356,8 @@ plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plug
## Miscellaneous
* Use [polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills).
* Use
[polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills).
* Use [Microformats](http://microformats.org/wiki/Main_Page) (via
[microdata](http://microformats.org/wiki/microdata)) for optimum search
@@ -358,7 +365,8 @@ plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plug
[visibility](https://webmasters.googleblog.com/2009/05/introducing-rich-snippets.html).
* If you're building a web app you may want [native style momentum scrolling in
iOS 5+](https://www.johanbrook.com/writings/native-style-momentum-scrolling-to-arrive-in-ios-5/)
iOS
5+](https://www.johanbrook.com/writings/native-style-momentum-scrolling-to-arrive-in-ios-5/)
using `-webkit-overflow-scrolling: touch`.
* If you want to disable the translation prompt in Chrome or block Google
@@ -389,8 +397,8 @@ scratch](http://www.rssboard.org/rss-specification)?
### Atom
Atom is similar to RSS, and you might prefer to use it instead of or in
addition to it. [See what Atom's all
Atom is similar to RSS, and you might prefer to use it instead of or in addition
to it. [See what Atom's all
about](https://en.wikipedia.org/wiki/Atom_(Web_standard)).
```html
@@ -399,16 +407,19 @@ about](https://en.wikipedia.org/wiki/Atom_(Web_standard)).
### Pingbacks
Your server may be notified when another site links to yours. The href
attribute should contain the location of your pingback service.
Your server may be notified when another site links to yours. The href attribute
should contain the location of your pingback service.
```html
<link rel="pingback" href="">
```
* High-level explanation: https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
* Step-by-step example case: https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
* PHP pingback service: https://web.archive.org/web/20131211032834/http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/
* High-level explanation:
https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
* Step-by-step example case:
https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
* PHP pingback service:
https://web.archive.org/web/20131211032834/http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/
@@ -425,11 +436,11 @@ Take full advantage of Facebook's support for complex data and activity by
following the [Open Graph
tutorial](https://developers.facebook.com/docs/sharing/webmasters/getting-started).
For a reference of Open Graph's markup and properties, you may check
[Facebook's Open Graph Protocol reference](https://ogp.me). Finally,
you can validate your markup with the [Facebook Object
Debugger](https://developers.facebook.com/tools/debug/) (needs
registration to Facebook).
For a reference of Open Graph's markup and properties, you may check [Facebook's
Open Graph Protocol reference](https://ogp.me). Finally, you can validate your
markup with the [Facebook Object
Debugger](https://developers.facebook.com/tools/debug/) (needs registration to
Facebook).
```html
<meta property="fb:app_id" content="123456789">
@@ -445,11 +456,13 @@ registration to Facebook).
### Twitter Cards
Twitter provides a snippet specification that serves a similar purpose to Open
Graph. In fact, Twitter will use Open Graph when Cards is not available. You
can read more about the various snippet formats and application process in the
[official Twitter Cards documentation](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
and you can validate your markup with the [Card validator](https://cards-dev.twitter.com/validator)
(needs registration to Twitter).
Graph. In fact, Twitter will use Open Graph when Cards is not available. You can
read more about the various snippet formats and application process in the
[official Twitter Cards
documentation](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
and you can validate your markup with the [Card
validator](https://cards-dev.twitter.com/validator) (needs registration to
Twitter).
```html
<meta name="twitter:card" content="summary">
@@ -463,18 +476,17 @@ and you can validate your markup with the [Card validator](https://cards-dev.twi
### Schema.org
Google also provides a snippet specification that serves a similar
purpose to Facebook's Open Graph or Twitter Cards. This metadata is a subset
of [schema.org's microdata vocabulary](https://schema.org/), which
covers many other schemas that can describe the content of your pages
to search engines. For this reason, this metadata is more generic for
SEO, notably for Google's search-engine, although this vocabulary is
also used by Microsoft, Pinterest and Yandex.
Google also provides a snippet specification that serves a similar purpose to
Facebook's Open Graph or Twitter Cards. This metadata is a subset of
[schema.org's microdata vocabulary](https://schema.org/), which covers many
other schemas that can describe the content of your pages to search engines. For
this reason, this metadata is more generic for SEO, notably for Google's
search-engine, although this vocabulary is also used by Microsoft, Pinterest and
Yandex.
You can validate your markup with the [Structured Data Testing
Tool](https://developers.google.com/structured-data/testing-tool/).
Also, please note that this markup requires to add attributes to your
top `html` tag.
Tool](https://developers.google.com/structured-data/testing-tool/). Also, please
note that this markup requires to add attributes to your top `html` tag.
```html
<html class="no-js" lang="" itemscope itemtype="https://schema.org/Article">
@@ -503,15 +515,16 @@ the cleaner, more accurate `https://www.example.com/cart.html`.
### Separate mobile URLs
If you use separate URLs for desktop and mobile users, you should consider
helping search engine algorithms better understand the configuration on your
web site.
helping search engine algorithms better understand the configuration on your web
site.
This can be done by adding the following annotations in your HTML pages:
* on the desktop page, add the `link rel="alternate"` tag pointing to the
corresponding mobile URL, e.g.:
`<link rel="alternate" media="only screen and (max-width: 640px)" href="https://m.example.com/page.html" >`
`<link rel="alternate" media="only screen and (max-width: 640px)"
href="https://m.example.com/page.html" >`
* on the mobile page, add the `link rel="canonical"` tag pointing to the
corresponding desktop URL, e.g.:
@@ -529,8 +542,8 @@ There are a couple of meta tags that provide information about a web app when
added to the Home Screen on iOS:
* Adding `apple-mobile-web-app-capable` will make your web app chrome-less and
provide the default iOS app view. You can control the color scheme of the
default view by adding `apple-mobile-web-app-status-bar-style`.
provide the default iOS app view. You can control the color scheme of the
default view by adding `apple-mobile-web-app-status-bar-style`.
```html
<meta name="apple-mobile-web-app-capable" content="yes">
@@ -538,7 +551,7 @@ default view by adding `apple-mobile-web-app-status-bar-style`.
```
* You can use `apple-mobile-web-app-title` to add a specific sites name for the
Home Screen icon. This works since iOS 6.
Home Screen icon. This works since iOS 6.
```html
<meta name="apple-mobile-web-app-title" content="">
@@ -554,9 +567,9 @@ on Apple's site.
Apple touch icons are used as icons when a user adds your webapp to the home
screen of aniOS devices.
Though the dimensions of the icon can vary between iOS devices and versions
one `180×180px` touch icon named `icon.png` and including the following in
the `<head>` of the page is enough:
Though the dimensions of the icon can vary between iOS devices and versions one
`180×180px` touch icon named `icon.png` and including the following in the
`<head>` of the page is enough:
```html
<link rel="apple-touch-icon" href="icon.png">
@@ -571,8 +584,8 @@ Icons](https://mathiasbynens.be/notes/touch-icons).
Apart from that it is possible to add start-up screens for web apps on iOS. This
basically works by defining `apple-touch-startup-image` with an according link
to the image. Since iOS devices have different screen resolutions it maybe
necessary to add media queries to detect which image to load. Here is an
example for an iPhone:
necessary to add media queries to detect which image to load. Here is an example
for an iPhone:
```html
<link rel="apple-touch-startup-image" media="(max-device-width: 480px) and (-webkit-min-device-pixel-ratio: 2)" href="img/startup.png">
@@ -597,10 +610,11 @@ Same applies to the touch icons:
### Theme Color
You can add the [`theme-color` meta extension](https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color)
in the `<head>` of your pages to suggest the color that browsers and
OSes should use if they customize the display of individual pages in
their UIs with varying colors.
You can add the [`theme-color` meta
extension](https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color)
in the `<head>` of your pages to suggest the color that browsers and OSes should
use if they customize the display of individual pages in their UIs with varying
colors.
```html
<meta name="theme-color" content="#ff69b4">
@@ -608,17 +622,19 @@ their UIs with varying colors.
The `content` attribute extension can take any valid CSS color.
Currently, the `theme-color` meta extension is supported by [Chrome 39+
for Android Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
Currently, the `theme-color` meta extension is supported by [Chrome 39+ for
Android
Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
## security.txt
When security risks in web services are discovered by users they often lack the
channels to disclose them properly. As a result, security issues may be left unreported.
channels to disclose them properly. As a result, security issues may be left
unreported.
Security.txt defines a standard to help organizations define the process for
users to disclose security vulnerabilities securely. Include a text
file on your server at `.well-known/security.txt` with the relevant contact details.
users to disclose security vulnerabilities securely. Include a text file on your
server at `.well-known/security.txt` with the relevant contact details.
Check [https://securitytxt.org/](https://securitytxt.org/) for more details.

26
dist/doc/faq.md vendored
View File

@@ -4,7 +4,8 @@ table of contents](TOC.md)
# Frequently asked questions
* [Why is the Google Analytics code at the bottom? Google recommends it be
placed in the `<head>`.](#why-is-the-google-analytics-code-at-the-bottom-google-recommends-it-be-placed-in-the-head)
placed in the
`<head>`.](#why-is-the-google-analytics-code-at-the-bottom-google-recommends-it-be-placed-in-the-head)
* [Do I need to upgrade my site each time a new version of HTML5 Boilerplate is
released?](#do-i-need-to-upgrade-my-site-each-time-a-new-version-of-html5-boilerplate-is-released)
* [Where can I get help with support
@@ -17,22 +18,23 @@ table of contents](TOC.md)
The main advantage of placing it in the `<head>` is that you will track the
user's `pageview` even if they leave the page before it has been fully loaded.
Here's a handy quote from [Mathias Bynens](https://mathiasbynens.be/notes/async-analytics-snippet#comment-50) about our placement choice.
Here's a handy quote from [Mathias
Bynens](https://mathiasbynens.be/notes/async-analytics-snippet#comment-50) about
our placement choice.
>I should point out that it’s Google — not me — recommending to place this
script before all other scripts in the document. The only real advantage is to
catch a pageView call if your page fails to load completely (for example, if
the user aborts loading, or quickly closes the page, etc.). Personally, I
wouldn’t count that as a page view, so I actually prefer to place this script
at the bottom, after all other scripts. This keeps all the scripts together and
reinforces that scripts at the bottom are the right move. (Usually I
concatenate and minify all my scripts into one .js file — the GA snippet being
the suffix.)
catch a pageView call if your page fails to load completely (for example, if the
user aborts loading, or quickly closes the page, etc.). Personally, I wouldn’t
count that as a page view, so I actually prefer to place this script at the
bottom, after all other scripts. This keeps all the scripts together and
reinforces that scripts at the bottom are the right move. (Usually I concatenate
and minify all my scripts into one .js file — the GA snippet being the suffix.)
## Do I need to upgrade my site each time a new version of HTML5 Boilerplate is released?
No, just as you don't normally replace the foundation of a house once it
was built. However, there is nothing stopping you from trying to work in the
latest changes, but you'll have to assess the costs/benefits of doing so.
No, just as you don't normally replace the foundation of a house once it was
built. However, there is nothing stopping you from trying to work in the latest
changes, but you'll have to assess the costs/benefits of doing so.
## Where can I get help with support questions?

173
dist/doc/html.md vendored
View File

@@ -14,14 +14,15 @@ By default, HTML5 Boilerplate provides two `html` pages:
### 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
explicitly add custom styles based on whether JavaScript is disabled (`.no-js`)
or enabled (`.js`). Using this technique also helps [avoid the
FOUC](https://www.paulirish.com/2009/avoiding-the-fouc-v3/).
### Language Attribute
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`
attribute in the `<html>` as in this example:
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` attribute in the `<html>` as in this example:
```html
<html class="no-js" lang="en">
@@ -30,48 +31,54 @@ attribute in the `<html>` as in this example:
### The order of the `<title>` and `<meta>` tags
The charset declaration (`<meta charset="utf-8">`) must be included completely
within the [first 1024 bytes of the document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
and should be specified as early as possible (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](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
within the [first 1024 bytes of the
document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
and should be specified as early as possible (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](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
in Internet Explorer
### Meta Description
The `description` meta tag provides a short description of the page.
In some situations this description is used as a part of the snippet
shown in the search results.
The `description` meta tag provides a short description of the page. In some
situations this description is used as a part of the snippet shown in the search
results.
```html
<meta name="description" content="This is a description">
```
Google's [Create good meta descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
Google's [Create good meta
descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
documentation has useful tips on creating an effective description.
### Mobile Viewport
There are a few different options that you can use with the [`viewport` meta
tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4 "Viewport and
Media Queries - The Complete Idiot's Guide"). You can find out more in [the
MDN Web Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag).
HTML5 Boilerplate comes with a simple setup that strikes a good balance for general use cases.
Media Queries - The Complete Idiot's Guide"). You can find out more in [the MDN
Web
Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag).
HTML5 Boilerplate comes with a simple setup that strikes a good balance for
general use cases.
```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you can do
so with additional viewport parameters. [Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
for details.
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you can
do so with additional viewport parameters. [Check the WebKit
blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) for
details.
### Web App Manifest
HTML5 Boilerplate includes a simple web app manifest file.
The web app manifest is a simple JSON file that allows you to control how your
app appears on a device's home screen, what it looks like when it launches
in that context and what happens when it is launched. This allows for much greater
app appears on a device's home screen, what it looks like when it launches in
that context and what happens when it is launched. This allows for much greater`
control over the UI of a saved site or web app on a mobile device.
It's linked to from the HTML as follows:
@@ -80,15 +87,18 @@ It's linked to from the HTML as follows:
<link rel="manifest" href="site.webmanifest">
```
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.
You should fill this file out with [more information about your site or application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
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. You
should fill this file out with [more information about your site or
application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
### Favicons and Touch Icon
The shortcut icons should be put in the root directory of your site. `favicon.ico`
is automatically picked up by browsers if it's placed in the root. HTML5
Boilerplate comes with a default set of icons (include favicon and one Apple
Touch Icon) that you can use as a baseline to create your own.
The shortcut icons should be put in the root directory of your site.
`favicon.ico` is automatically picked up by browsers if it's placed in the root.
HTML5 Boilerplate comes with a default set of icons (include favicon and one
Apple Touch Icon) that you can use as a baseline to create your own.
Please refer to the more detailed description in the [Extend section](extend.md)
of these docs.
@@ -96,28 +106,31 @@ of these docs.
### The Content Area
The central part of the boilerplate template is pretty much empty. This is
intentional, in order to make the boilerplate suitable for both web page and
web app development.
intentional, in order to make the boilerplate suitable for both web page and web
app development.
### Modernizr
HTML5 Boilerplate uses a custom build of Modernizr.
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes to
the `html` element based on the results of feature test and which ensures that
all browsers can make use of HTML5 elements (as it includes the HTML5 Shiv).
This allows you to target parts of your CSS and JavaScript based on the
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes
to the `html` element based on the results of feature test and which ensures
that all browsers can make use of HTML5 elements (as it includes the HTML5
Shiv). This allows you to target parts of your CSS and JavaScript based on the
features supported by a browser.
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
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).
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 [Modernizr command line
utility](https://www.npmjs.com/package/modernizr-cli).
### What About Polyfills?
If you need to include [polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill)
in your project, you must make sure those load before any other JavaScript. If you're
using a polyfill CDN service, like [polyfill.io](https://polyfill.io/),
just put it before the other scripts in the bottom of the page:
If you need to include
[polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill) in your
project, you must make sure those load before any other JavaScript. If you're
using a polyfill CDN service, like [polyfill.io](https://polyfill.io/), just put
it before the other scripts in the bottom of the page:
```html
<script src="js/vendor/modernizr-3.10.0.min.js"></script>
@@ -130,62 +143,68 @@ just put it before the other scripts in the bottom of the page:
```
If you like to just include the polyfills yourself, you could include them in
`js/plugins.js`. When you have a bunch of polyfills to load in, you could
also create a `polyfills.js` file in the `js/vendor` directory or include the files
individually and combine them using a build tool. Always ensure that the polyfills
are all loaded before any other JavaScript.
`js/plugins.js`. When you have a bunch of polyfills to load in, you could also
create a `polyfills.js` file in the `js/vendor` directory or include the files
individually and combine them using a build tool. Always ensure that the
polyfills are all loaded before any other JavaScript.
There are some misconceptions about Modernizr and polyfills. It's important
to understand that Modernizr just handles feature checking, not polyfilling
itself. The only thing Modernizr does regarding polyfills is that the team
maintains [a huge list of cross Browser polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
There are some misconceptions about Modernizr and polyfills. It's important to
understand that Modernizr just handles feature checking, not polyfilling itself.
The only thing Modernizr does regarding polyfills is that the team maintains [a
huge list of cross Browser
polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
### jQuery CDN for jQuery
The jQuery CDN version of the jQuery JavaScript library is referenced towards
the bottom of the page. A local fallback of jQuery is included for rare instances
when the CDN version might not be available, and to facilitate offline
the bottom of the page. A local fallback of jQuery is included for rare
instances when the CDN version might not be available, and to facilitate offline
development.
The jQuery CDN version was chosen over other potential candidates
([like Google's Hosted Libraries](https://developers.google.com/speed/libraries/))
The jQuery CDN version was chosen over other potential candidates ([like
Google's Hosted Libraries](https://developers.google.com/speed/libraries/))
because it's fast ([comparable or faster than Google by some
measures](https://www.cdnperf.com/#jsdelivr,cdnjs,google,yandex,microsoft,jquery,bootstrapcdn/https/90))
and, (unlike Google's CDN) is available to China's hundreds of millions of internet users.
For many years we [chose](https://github.com/h5bp/html5-boilerplate/issues/1191)
the Google Hosted version over the jQuery CDN because it was available
over HTTPS (the jQuery CDN was not,) and it offered a better chance of
hitting the cache lottery owing to the popularity of the Google CDN.
The first issue is no longer valid and the second is far outweighed by
being able to serve jQuery to users in China.
and, (unlike Google's CDN) is available to China's hundreds of millions of
internet users. For many years we
[chose](https://github.com/h5bp/html5-boilerplate/issues/1191) the Google Hosted
version over the jQuery CDN because it was available over HTTPS (the jQuery CDN
was not,) and it offered a better chance of hitting the cache lottery owing to
the popularity of the Google CDN. The first issue is no longer valid and the
second is far outweighed by being able to serve jQuery to users in China.
While the jQuery CDN is a strong default solution your site or application may
require a different configuration. Testing your site with services like
[WebPageTest](https://www.webpagetest.org/) and browser tools like
[PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) will help you examine the real
world performance of your site and can show where you can optimize your specific
site or application.
[WebPageTest](https://www.webpagetest.org/) and browser tools like [PageSpeed
Insights](https://developers.google.com/speed/pagespeed/insights/) will help you
examine the real world performance of your site and can show where you can
optimize your specific site or application.
### Google Universal Analytics Tracking Code
Finally, an optimized version of the Google Universal Analytics tracking code is
included.
We use `analytics.js` rather than the newer `gtag.js` as
[it's faster and supports tasks and plugins](https://github.com/philipwalton/analyticsjs-boilerplate/issues/19#issuecomment-333714370)
We use `analytics.js` rather than the newer `gtag.js` as [it's faster and
supports tasks and
plugins](https://github.com/philipwalton/analyticsjs-boilerplate/issues/19#issuecomment-333714370)
Starting with version 8 we, by default, [anonymize IP addresses](href="https://support.google.com/analytics/answer/2763052?hl=en).
By default Google Analytics records the full IP address of a user visiting the site, but
that full IP address is never available to the Google Analytics property admin.
By anonymizing the IP address you can make your site more GDPR-compliant as a
full IP address can be defined as PII (personally identifiable information.)
Starting with version 8 we, by default, [anonymize IP
addresses](href="https://support.google.com/analytics/answer/2763052?hl=en). By
default Google Analytics records the full IP address of a user visiting the
site, but that full IP address is never available to the Google Analytics
property admin. By anonymizing the IP address you can make your site more
GDPR-compliant as a full IP address can be defined as PII (personally
identifiable information.)
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).
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).
Google recommends that this script be placed at the top of the page.
Factors to consider: if you place this script at the top of the page, you’ll
be able to count users who don’t fully load the page, and you’ll incur the max
number of simultaneous connections of the browser.
Google recommends that this script be placed at the top of the page. Factors to
consider: if you place this script at the top of the page, you’ll be able to
count users who don’t fully load the page, and you’ll incur the max number of
simultaneous connections of the browser.
Further information:
@@ -193,9 +212,9 @@ Further information:
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
**N.B.** The Google Analytics snippet is included by default mainly
because Google Analytics is [currently one of the most popular tracking
**N.B.** The Google Analytics snippet is included by default mainly because
Google Analytics is [currently one of the most popular tracking
solutions](https://trends.builtwith.com/analytics/Google-Analytics) out there.
However, its usage isn't set in stone, and you SHOULD consider exploring the
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software)
and use whatever suits your needs best.
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software) and
use whatever suits your needs best.

22
dist/doc/js.md vendored
View File

@@ -7,22 +7,22 @@ Information about the default JavaScript included in the project.
## main.js
This file can be used to contain or reference your site/app JavaScript code.
If you're working on something more advanced you might replace this file
entirely. That's cool.
This file can be used to contain or reference your site/app JavaScript code. If
you're working on something more advanced you might replace this file entirely.
That's cool.
## plugins.js
This file can be used to contain all your plugins, such as jQuery plugins and
other 3rd party scripts for a simple site.
One approach is to put jQuery plugins inside of a `(function($){ ...
})(jQuery);` closure to make sure they're in the jQuery namespace safety
blanket. Read more about [jQuery plugin authoring](https://learn.jquery.com/plugins/).
One approach is to put jQuery plugins inside of a `(function($){ ...})(jQuery);`
closure to make sure they're in the jQuery namespace safety blanket. Read more
about [jQuery plugin authoring](https://learn.jquery.com/plugins/).
By default the `plugins.js` file contains a small script to avoid `console`
errors in browsers that lack a `console`. The script will make sure that, if
a console method isn't available, that method will have the value of empty
errors in browsers that lack a `console`. The script will make sure that, if a
console method isn't available, that method will have the value of empty
function, thus, preventing the browser from throwing an error.
## vendor
@@ -30,6 +30,6 @@ function, thus, preventing the browser from throwing an error.
This directory can be used to contain all 3rd party library code.
Minified versions of the latest jQuery and Modernizr libraries are included by
default. You may wish to create your own [custom Modernizr
build with the online builder](https://modernizr.com/download/) or [command
line tool](https://modernizr.com/docs#command-line-config).
default. You may wish to create your own [custom Modernizr build with the online
builder](https://modernizr.com/download/) or [command line
tool](https://modernizr.com/docs#command-line-config).

21
dist/doc/usage.md vendored
View File

@@ -27,7 +27,7 @@ HTML5 Boilerplate is a starting point, not a destination.
A basic HTML5 Boilerplate site initially looks something like this:
``` bash
```
.
├── css
│ ├── main.css
@@ -80,8 +80,9 @@ refer to the [Apache Server Configs
repository](https://github.com/h5bp/server-configs-apache).
Host your site on a server other than Apache? You're likely to find the
corresponding server configs project listed in our [Server Configs
](https://github.com/h5bp/server-configs/blob/master/README.md) repository.
corresponding server configs project listed in our [Server
Configs](https://github.com/h5bp/server-configs/blob/master/README.md)
repository.
### 404.html
@@ -91,14 +92,14 @@ A helpful custom 404 to get you started.
This file contains all settings regarding custom tiles for IE11 and Edge.
For more info on this topic, please refer to
[Microsoft's Docs](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
For more info on this topic, please refer to [Microsoft's
Docs](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
### .editorconfig
The `.editorconfig` file is provided in order to encourage and help you and
your team to maintain consistent coding styles between different
editors and IDEs. [Read more about the `.editorconfig` file](misc.md#editorconfig).
The `.editorconfig` file is provided in order to encourage and help you and your
team to maintain consistent coding styles between different editors and IDEs.
[Read more about the `.editorconfig` file](misc.md#editorconfig).
### index.html
@@ -123,8 +124,8 @@ Edit this file to include any pages you need hidden from search engines.
### Icons
Replace the default `favicon.ico`, `tile.png`, `tile-wide.png` and Apple
Touch Icon with your own.
Replace the default `favicon.ico`, `tile.png`, `tile-wide.png` and Apple Touch
Icon with your own.
If you want to use different Apple Touch Icons for different resolutions please
refer to the [according documentation](extend.md#apple-touch-icons).

18
src/doc/TOC.md
View File

@@ -14,21 +14,23 @@
## Development
* [Extending and customizing HTML5 Boilerplate](extend.md) — Going further
with the boilerplate.
* [Extending and customizing HTML5 Boilerplate](extend.md) — Going further with
the boilerplate.
## Related projects
The [H5BP organization](https://github.com/h5bp) maintains several projects
that complement HTML5 Boilerplate, projects that can help you improve different
The [H5BP organization](https://github.com/h5bp) maintains several projects that
complement HTML5 Boilerplate, projects that can help you improve different
aspects of your website/web app (e.g.: the performance, security, etc.).
* [Server Configs](https://github.com/h5bp/server-configs) — Fast and
smart configurations for web servers such as Apache and Nginx.
* [Server Configs](https://github.com/h5bp/server-configs) — Fast and smart
configurations for web servers such as Apache and Nginx.
* [Apache](https://github.com/h5bp/server-configs-apache)
* [Google App Engine (GAE)](https://github.com/h5bp/server-configs-gae)
* [Internet Information Services (IIS)](https://github.com/h5bp/server-configs-iis)
* [Internet Information Services
(IIS)](https://github.com/h5bp/server-configs-iis)
* [lighttpd](https://github.com/h5bp/server-configs-lighttpd)
* [Nginx](https://github.com/h5bp/server-configs-nginx)
* [Node.js](https://github.com/h5bp/server-configs-node)
* [Front-end Developer Interview Questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions)
* [Front-end Developer Interview
Questions](https://github.com/h5bp/Front-end-Developer-Interview-Questions)

19
src/doc/css.md
View File

@@ -8,17 +8,17 @@ HTML5 Boilerplate's CSS includes:
* [Normalize.css](#normalizecss)
* [main.css](#maincss)
This starting CSS does not rely on the presence of
[conditional class names](https://www.paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/),
This starting CSS does not rely on the presence of [conditional class
names](https://www.paulirish.com/2008/conditional-stylesheets-vs-css-hacks-answer-neither/),
or [Modernizr](https://modernizr.com/), and it is ready to use no matter what
your development preferences happen to be.
## Normalize.css
In order to make browsers render all elements more consistently and in line
with modern standards, we include Normalize.css — a modern, HTML5-ready
alternative to CSS resets.
In order to make browsers render all elements more consistently and in line with
modern standards, we include Normalize.css — a modern, HTML5-ready alternative
to CSS resets.
As opposed to CSS resets, Normalize.css:
@@ -35,8 +35,7 @@ page](https://necolas.github.io/normalize.css/).
## main.css
Several base styles are included that build upon `Normalize.css`. These
styles:
Several base styles are included that build upon `Normalize.css`. These styles:
* provide basic typography settings that improve text readability
* protect against unwanted `text-shadow` during text highlighting
@@ -45,4 +44,8 @@ styles:
* style the prompt that is displayed to users using an outdated browser
* and more...
These styles are included in [main.css](https://github.com/h5bp/html5-boilerplate/blob/master/dist/css/main.css). See the [main.css](https://github.com/h5bp/main.css) project [documentation](https://github.com/h5bp/main.css/blob/master/README.md#features) for a full discussion of these styles.
These styles are included in
[main.css](https://github.com/h5bp/html5-boilerplate/blob/master/dist/css/main.css).
See the [main.css](https://github.com/h5bp/main.css) project
[documentation](https://github.com/h5bp/main.css/blob/master/README.md#features)
for a full discussion of these styles.

198
src/doc/extend.md
View File

@@ -4,8 +4,8 @@ table of contents](TOC.md)
# Extend and customise HTML5 Boilerplate
Here is some useful advice for how you can make your project with HTML5
Boilerplate even better. We don't want to include it all by default, as
not everything fits with everyone's needs.
Boilerplate even better. We don't want to include it all by default, as not
everything fits with everyone's needs.
* [App Stores](#app-stores)
@@ -24,8 +24,11 @@ not everything fits with everyone's needs.
### Smart App Banners in iOS 6+ Safari
Stop bothering everyone with gross modals advertising your entry in the
App Store. Including the following [meta tag](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html) will unobtrusively give the user the option to download your iOS app, or open it with some data about the user's current state on the website.
Stop bothering everyone with gross modals advertising your entry in the App
Store. Including the following [meta
tag](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html)
will unobtrusively give the user the option to download your iOS app, or open it
with some data about the user's current state on the website.
```html
<meta name="apple-itunes-app" content="app-id=APP_ID,app-argument=SOME_TEXT">
@@ -35,18 +38,17 @@ App Store. Including the following [meta tag](https://developer.apple.com/librar
In short, DNS Prefetching is a method of informing the browser of domain names
referenced on a site so that the client can resolve the DNS for those hosts,
cache them, and when it comes time to use them, have a faster turn around on
the request.
cache them, and when it comes time to use them, have a faster turn around on the
request.
### Implicit prefetches
There is a lot of prefetching done for you automatically by the browser. When
the browser encounters an anchor in your html that does not share the same
domain name as the current location the browser requests, from the client OS,
the IP address for this new domain. The client first checks its cache and
then, lacking a cached copy, makes a request from a DNS server. These requests
happen in the background and are not meant to block the rendering of the
page.
the IP address for this new domain. The client first checks its cache and then,
lacking a cached copy, makes a request from a DNS server. These requests happen
in the background and are not meant to block the rendering of the page.
The goal of this is that when the foreign IP address is finally needed it will
already be in the client cache and will not block the loading of the foreign
@@ -68,9 +70,9 @@ FOREIGN DOMAINS.
### Explicit prefetches
Typically the browser only scans the HTML for foreign domains. If you have
resources that are outside of your HTML (a javascript request to a remote
server or a CDN that hosts content that may not be present on every page of
your site, for example) then you can queue up a domain name to be prefetched.
resources that are outside of your HTML (a javascript request to a remote server
or a CDN that hosts content that may not be present on every page of your site,
for example) then you can queue up a domain name to be prefetched.
```html
<link rel="dns-prefetch" href="//example.com">
@@ -80,8 +82,8 @@ your site, for example) then you can queue up a domain name to be prefetched.
You can use as many of these as you need, but it's best if they are all
immediately after the [Meta
Charset](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-charset)
element (which should go right at the top of the `head`), so the browser can
act on them ASAP.
element (which should go right at the top of the `head`), so the browser can act
on them ASAP.
#### Common Prefetch Links
@@ -126,7 +128,9 @@ ga('create', 'UA-XXXXX-X', 'auto'); ga('send', 'pageview');
To customize further, see Google's [Advanced
Setup](https://developers.google.com/analytics/devguides/collection/analyticsjs/),
[Pageview](https://developers.google.com/analytics/devguides/collection/analyticsjs/pages),
and [Event](https://developers.google.com/analytics/devguides/collection/analyticsjs/events) Docs.
and
[Event](https://developers.google.com/analytics/devguides/collection/analyticsjs/events)
Docs.
### Track jQuery AJAX requests in Google Analytics
@@ -204,7 +208,8 @@ $(function(){
Enabling your application for pinning will allow IE users to add it to their
Windows Taskbar and Start Menu. This comes with a range of new tools that you
can easily configure with the elements below. See more [documentation on IE
Pinned Sites](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/samples/gg491731(v%3dvs.85)).
Pinned
Sites](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/samples/gg491731(v%3dvs.85)).
### Name the Pinned Site for Windows
@@ -238,8 +243,8 @@ track the number of pinned users, like so:
### Recolor IE's controls manually for a Pinned Site
IE will automatically use the overall color of your Pinned Site's favicon to
shade its browser buttons. UNLESS you give it another color here. Only use
named colors (`red`) or hex colors (`#ff0000`).
shade its browser buttons. UNLESS you give it another color here. Only use named
colors (`red`) or hex colors (`#ff0000`).
```html
<meta name="msapplication-navbutton-color" content="#ff0000">
@@ -248,8 +253,7 @@ named colors (`red`) or hex colors (`#ff0000`).
### Manually set the window size of a Pinned Site
If the site should open at a certain window size once pinned, you can specify
the dimensions here. It only supports static pixel dimensions. 800x600
minimum.
the dimensions here. It only supports static pixel dimensions. 800x600 minimum.
```html
<meta name="msapplication-window" content="width=800;height=600">
@@ -259,8 +263,7 @@ minimum.
Add Jump List Tasks that will appear when the Pinned Site's icon gets a
right-click. Each Task goes to the specified URL, and gets its own mini icon
(essentially a favicon, a 16x16 .ICO). You can add as many of these as you
need.
(essentially a favicon, a 16x16 .ICO). You can add as many of these as you need.
```html
<meta name="msapplication-task" content="name=Task 1;action-uri=http://host/Page1.html;icon-uri=http://host/icon1.ico">
@@ -273,22 +276,24 @@ Windows 8 adds the ability for you to provide a PNG tile image and specify the
tile's background color. [Full details on the IE
blog](https://blogs.msdn.microsoft.com/ie/2012/06/08/high-quality-visuals-for-pinned-sites-in-windows-8/).
* Create a 144x144 image of your site icon, filling all of the canvas, and
using a transparent background.
* Save this image as a 32-bit PNG and optimize it without reducing
colour-depth. It can be named whatever you want (e.g. `metro-tile.png`).
* To reference the tile and its color, add the HTML `meta` elements described
in the IE Blog post.
* Create a 144x144 image of your site icon, filling all of the canvas, and using
a transparent background.
* Save this image as a 32-bit PNG and optimize it without reducing colour-depth.
It can be named whatever you want (e.g. `metro-tile.png`).
* To reference the tile and its color, add the HTML `meta` elements described in
the IE Blog post.
### (Windows 8) Badges for Pinned Sites
IE will poll an XML document for badge information to display on your app's
tile in the Start screen. The user will be able to receive these badge updates
even when your app isn't actively running. The badge's value can be a number,
or one of a predefined list of glyphs.
IE will poll an XML document for badge information to display on your app's tile
in the Start screen. The user will be able to receive these badge updates even
when your app isn't actively running. The badge's value can be a number, or one
of a predefined list of glyphs.
* [Tutorial on IEBlog with link to badge XML schema](https://blogs.msdn.microsoft.com/ie/2012/04/03/pinned-sites-in-windows-8/)
* [Available badge values](https://docs.microsoft.com/en-us/uwp/schemas/tiles/badgeschema/element-badge)
* [Tutorial on IEBlog with link to badge XML
schema](https://blogs.msdn.microsoft.com/ie/2012/04/03/pinned-sites-in-windows-8/)
* [Available badge
values](https://docs.microsoft.com/en-us/uwp/schemas/tiles/badgeschema/element-badge)
```html
<meta name="msapplication-badge" value="frequency=NUMBER_IN_MINUTES;polling-uri=https://www.example.com/path/to/file.xml">
@@ -296,16 +301,18 @@ or one of a predefined list of glyphs.
### Disable link highlighting upon tap in IE10
Similar to [-webkit-tap-highlight-color](https://davidwalsh.name/mobile-highlight-color)
in iOS Safari. Unlike that CSS property, this is an HTML meta element, and its
Similar to
[-webkit-tap-highlight-color](https://davidwalsh.name/mobile-highlight-color) in
iOS Safari. Unlike that CSS property, this is an HTML meta element, and its
value is boolean rather than a color. It's all or nothing.
```html
<meta name="msapplication-tap-highlight" content="no" />
```
You can read about this useful element and more techniques in
[Microsoft's documentation on adapting WebKit-oriented apps for IE10](https://blogs.windows.com/buildingapps/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10/)
You can read about this useful element and more techniques in [Microsoft's
documentation on adapting WebKit-oriented apps for
IE10](https://blogs.windows.com/buildingapps/2012/11/15/adapting-your-webkit-optimized-site-for-internet-explorer-10/)
## Search
@@ -317,9 +324,8 @@ Submit it to search engine tool:
* [Google](https://www.google.com/webmasters/tools/sitemap-list)
* [Bing](https://www.bing.com/toolbox/webmaster)
* [Yandex](https://webmaster.yandex.com/)
* [Baidu](https://zhanzhang.baidu.com/)
OR
Insert the following line anywhere in your robots.txt file, specifying the path to your sitemap:
* [Baidu](https://zhanzhang.baidu.com/) OR Insert the following line anywhere in
your robots.txt file, specifying the path to your sitemap:
```
Sitemap: https://example.com/sitemap_location.xml
```
@@ -350,7 +356,8 @@ plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plug
## Miscellaneous
* Use [polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills).
* Use
[polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-browser-Polyfills).
* Use [Microformats](http://microformats.org/wiki/Main_Page) (via
[microdata](http://microformats.org/wiki/microdata)) for optimum search
@@ -358,7 +365,8 @@ plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plug
[visibility](https://webmasters.googleblog.com/2009/05/introducing-rich-snippets.html).
* If you're building a web app you may want [native style momentum scrolling in
iOS 5+](https://www.johanbrook.com/writings/native-style-momentum-scrolling-to-arrive-in-ios-5/)
iOS
5+](https://www.johanbrook.com/writings/native-style-momentum-scrolling-to-arrive-in-ios-5/)
using `-webkit-overflow-scrolling: touch`.
* If you want to disable the translation prompt in Chrome or block Google
@@ -389,8 +397,8 @@ scratch](http://www.rssboard.org/rss-specification)?
### Atom
Atom is similar to RSS, and you might prefer to use it instead of or in
addition to it. [See what Atom's all
Atom is similar to RSS, and you might prefer to use it instead of or in addition
to it. [See what Atom's all
about](https://en.wikipedia.org/wiki/Atom_(Web_standard)).
```html
@@ -399,16 +407,19 @@ about](https://en.wikipedia.org/wiki/Atom_(Web_standard)).
### Pingbacks
Your server may be notified when another site links to yours. The href
attribute should contain the location of your pingback service.
Your server may be notified when another site links to yours. The href attribute
should contain the location of your pingback service.
```html
<link rel="pingback" href="">
```
* High-level explanation: https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
* Step-by-step example case: https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
* PHP pingback service: https://web.archive.org/web/20131211032834/http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/
* High-level explanation:
https://codex.wordpress.org/Introduction_to_Blogging#Pingbacks
* Step-by-step example case:
https://www.hixie.ch/specs/pingback/pingback-1.0#TOC5
* PHP pingback service:
https://web.archive.org/web/20131211032834/http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/
@@ -425,11 +436,11 @@ Take full advantage of Facebook's support for complex data and activity by
following the [Open Graph
tutorial](https://developers.facebook.com/docs/sharing/webmasters/getting-started).
For a reference of Open Graph's markup and properties, you may check
[Facebook's Open Graph Protocol reference](https://ogp.me). Finally,
you can validate your markup with the [Facebook Object
Debugger](https://developers.facebook.com/tools/debug/) (needs
registration to Facebook).
For a reference of Open Graph's markup and properties, you may check [Facebook's
Open Graph Protocol reference](https://ogp.me). Finally, you can validate your
markup with the [Facebook Object
Debugger](https://developers.facebook.com/tools/debug/) (needs registration to
Facebook).
```html
<meta property="fb:app_id" content="123456789">
@@ -445,11 +456,13 @@ registration to Facebook).
### Twitter Cards
Twitter provides a snippet specification that serves a similar purpose to Open
Graph. In fact, Twitter will use Open Graph when Cards is not available. You
can read more about the various snippet formats and application process in the
[official Twitter Cards documentation](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
and you can validate your markup with the [Card validator](https://cards-dev.twitter.com/validator)
(needs registration to Twitter).
Graph. In fact, Twitter will use Open Graph when Cards is not available. You can
read more about the various snippet formats and application process in the
[official Twitter Cards
documentation](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards),
and you can validate your markup with the [Card
validator](https://cards-dev.twitter.com/validator) (needs registration to
Twitter).
```html
<meta name="twitter:card" content="summary">
@@ -463,18 +476,17 @@ and you can validate your markup with the [Card validator](https://cards-dev.twi
### Schema.org
Google also provides a snippet specification that serves a similar
purpose to Facebook's Open Graph or Twitter Cards. This metadata is a subset
of [schema.org's microdata vocabulary](https://schema.org/), which
covers many other schemas that can describe the content of your pages
to search engines. For this reason, this metadata is more generic for
SEO, notably for Google's search-engine, although this vocabulary is
also used by Microsoft, Pinterest and Yandex.
Google also provides a snippet specification that serves a similar purpose to
Facebook's Open Graph or Twitter Cards. This metadata is a subset of
[schema.org's microdata vocabulary](https://schema.org/), which covers many
other schemas that can describe the content of your pages to search engines. For
this reason, this metadata is more generic for SEO, notably for Google's
search-engine, although this vocabulary is also used by Microsoft, Pinterest and
Yandex.
You can validate your markup with the [Structured Data Testing
Tool](https://developers.google.com/structured-data/testing-tool/).
Also, please note that this markup requires to add attributes to your
top `html` tag.
Tool](https://developers.google.com/structured-data/testing-tool/). Also, please
note that this markup requires to add attributes to your top `html` tag.
```html
<html class="no-js" lang="" itemscope itemtype="https://schema.org/Article">
@@ -503,15 +515,16 @@ the cleaner, more accurate `https://www.example.com/cart.html`.
### Separate mobile URLs
If you use separate URLs for desktop and mobile users, you should consider
helping search engine algorithms better understand the configuration on your
web site.
helping search engine algorithms better understand the configuration on your web
site.
This can be done by adding the following annotations in your HTML pages:
* on the desktop page, add the `link rel="alternate"` tag pointing to the
corresponding mobile URL, e.g.:
`<link rel="alternate" media="only screen and (max-width: 640px)" href="https://m.example.com/page.html" >`
`<link rel="alternate" media="only screen and (max-width: 640px)"
href="https://m.example.com/page.html" >`
* on the mobile page, add the `link rel="canonical"` tag pointing to the
corresponding desktop URL, e.g.:
@@ -529,8 +542,8 @@ There are a couple of meta tags that provide information about a web app when
added to the Home Screen on iOS:
* Adding `apple-mobile-web-app-capable` will make your web app chrome-less and
provide the default iOS app view. You can control the color scheme of the
default view by adding `apple-mobile-web-app-status-bar-style`.
provide the default iOS app view. You can control the color scheme of the
default view by adding `apple-mobile-web-app-status-bar-style`.
```html
<meta name="apple-mobile-web-app-capable" content="yes">
@@ -538,7 +551,7 @@ default view by adding `apple-mobile-web-app-status-bar-style`.
```
* You can use `apple-mobile-web-app-title` to add a specific sites name for the
Home Screen icon. This works since iOS 6.
Home Screen icon. This works since iOS 6.
```html
<meta name="apple-mobile-web-app-title" content="">
@@ -554,9 +567,9 @@ on Apple's site.
Apple touch icons are used as icons when a user adds your webapp to the home
screen of aniOS devices.
Though the dimensions of the icon can vary between iOS devices and versions
one `180×180px` touch icon named `icon.png` and including the following in
the `<head>` of the page is enough:
Though the dimensions of the icon can vary between iOS devices and versions one
`180×180px` touch icon named `icon.png` and including the following in the
`<head>` of the page is enough:
```html
<link rel="apple-touch-icon" href="icon.png">
@@ -571,8 +584,8 @@ Icons](https://mathiasbynens.be/notes/touch-icons).
Apart from that it is possible to add start-up screens for web apps on iOS. This
basically works by defining `apple-touch-startup-image` with an according link
to the image. Since iOS devices have different screen resolutions it maybe
necessary to add media queries to detect which image to load. Here is an
example for an iPhone:
necessary to add media queries to detect which image to load. Here is an example
for an iPhone:
```html
<link rel="apple-touch-startup-image" media="(max-device-width: 480px) and (-webkit-min-device-pixel-ratio: 2)" href="img/startup.png">
@@ -597,10 +610,11 @@ Same applies to the touch icons:
### Theme Color
You can add the [`theme-color` meta extension](https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color)
in the `<head>` of your pages to suggest the color that browsers and
OSes should use if they customize the display of individual pages in
their UIs with varying colors.
You can add the [`theme-color` meta
extension](https://html.spec.whatwg.org/multipage/semantics.html#meta-theme-color)
in the `<head>` of your pages to suggest the color that browsers and OSes should
use if they customize the display of individual pages in their UIs with varying
colors.
```html
<meta name="theme-color" content="#ff69b4">
@@ -608,17 +622,19 @@ their UIs with varying colors.
The `content` attribute extension can take any valid CSS color.
Currently, the `theme-color` meta extension is supported by [Chrome 39+
for Android Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
Currently, the `theme-color` meta extension is supported by [Chrome 39+ for
Android
Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
## security.txt
When security risks in web services are discovered by users they often lack the
channels to disclose them properly. As a result, security issues may be left unreported.
channels to disclose them properly. As a result, security issues may be left
unreported.
Security.txt defines a standard to help organizations define the process for
users to disclose security vulnerabilities securely. Include a text
file on your server at `.well-known/security.txt` with the relevant contact details.
users to disclose security vulnerabilities securely. Include a text file on your
server at `.well-known/security.txt` with the relevant contact details.
Check [https://securitytxt.org/](https://securitytxt.org/) for more details.

26
src/doc/faq.md
View File

@@ -4,7 +4,8 @@ table of contents](TOC.md)
# Frequently asked questions
* [Why is the Google Analytics code at the bottom? Google recommends it be
placed in the `<head>`.](#why-is-the-google-analytics-code-at-the-bottom-google-recommends-it-be-placed-in-the-head)
placed in the
`<head>`.](#why-is-the-google-analytics-code-at-the-bottom-google-recommends-it-be-placed-in-the-head)
* [Do I need to upgrade my site each time a new version of HTML5 Boilerplate is
released?](#do-i-need-to-upgrade-my-site-each-time-a-new-version-of-html5-boilerplate-is-released)
* [Where can I get help with support
@@ -17,22 +18,23 @@ table of contents](TOC.md)
The main advantage of placing it in the `<head>` is that you will track the
user's `pageview` even if they leave the page before it has been fully loaded.
Here's a handy quote from [Mathias Bynens](https://mathiasbynens.be/notes/async-analytics-snippet#comment-50) about our placement choice.
Here's a handy quote from [Mathias
Bynens](https://mathiasbynens.be/notes/async-analytics-snippet#comment-50) about
our placement choice.
>I should point out that it’s Google — not me — recommending to place this
script before all other scripts in the document. The only real advantage is to
catch a pageView call if your page fails to load completely (for example, if
the user aborts loading, or quickly closes the page, etc.). Personally, I
wouldn’t count that as a page view, so I actually prefer to place this script
at the bottom, after all other scripts. This keeps all the scripts together and
reinforces that scripts at the bottom are the right move. (Usually I
concatenate and minify all my scripts into one .js file — the GA snippet being
the suffix.)
catch a pageView call if your page fails to load completely (for example, if the
user aborts loading, or quickly closes the page, etc.). Personally, I wouldn’t
count that as a page view, so I actually prefer to place this script at the
bottom, after all other scripts. This keeps all the scripts together and
reinforces that scripts at the bottom are the right move. (Usually I concatenate
and minify all my scripts into one .js file — the GA snippet being the suffix.)
## Do I need to upgrade my site each time a new version of HTML5 Boilerplate is released?
No, just as you don't normally replace the foundation of a house once it
was built. However, there is nothing stopping you from trying to work in the
latest changes, but you'll have to assess the costs/benefits of doing so.
No, just as you don't normally replace the foundation of a house once it was
built. However, there is nothing stopping you from trying to work in the latest
changes, but you'll have to assess the costs/benefits of doing so.
## Where can I get help with support questions?

173
src/doc/html.md
View File

@@ -14,14 +14,15 @@ By default, HTML5 Boilerplate provides two `html` pages:
### 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
explicitly add custom styles based on whether JavaScript is disabled (`.no-js`)
or enabled (`.js`). Using this technique also helps [avoid the
FOUC](https://www.paulirish.com/2009/avoiding-the-fouc-v3/).
### Language Attribute
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`
attribute in the `<html>` as in this example:
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` attribute in the `<html>` as in this example:
```html
<html class="no-js" lang="en">
@@ -30,48 +31,54 @@ attribute in the `<html>` as in this example:
### The order of the `<title>` and `<meta>` tags
The charset declaration (`<meta charset="utf-8">`) must be included completely
within the [first 1024 bytes of the document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
and should be specified as early as possible (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](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
within the [first 1024 bytes of the
document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
and should be specified as early as possible (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](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
in Internet Explorer
### Meta Description
The `description` meta tag provides a short description of the page.
In some situations this description is used as a part of the snippet
shown in the search results.
The `description` meta tag provides a short description of the page. In some
situations this description is used as a part of the snippet shown in the search
results.
```html
<meta name="description" content="This is a description">
```
Google's [Create good meta descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
Google's [Create good meta
descriptions](https://support.google.com/webmasters/answer/35624?hl=en#meta-descriptions)
documentation has useful tips on creating an effective description.
### Mobile Viewport
There are a few different options that you can use with the [`viewport` meta
tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4 "Viewport and
Media Queries - The Complete Idiot's Guide"). You can find out more in [the
MDN Web Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag).
HTML5 Boilerplate comes with a simple setup that strikes a good balance for general use cases.
Media Queries - The Complete Idiot's Guide"). You can find out more in [the MDN
Web
Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag).
HTML5 Boilerplate comes with a simple setup that strikes a good balance for
general use cases.
```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you can do
so with additional viewport parameters. [Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
for details.
If you want to take advantage of edge-to-edge displays of iPhone X/XS/XR you can
do so with additional viewport parameters. [Check the WebKit
blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) for
details.
### Web App Manifest
HTML5 Boilerplate includes a simple web app manifest file.
The web app manifest is a simple JSON file that allows you to control how your
app appears on a device's home screen, what it looks like when it launches
in that context and what happens when it is launched. This allows for much greater
app appears on a device's home screen, what it looks like when it launches in
that context and what happens when it is launched. This allows for much greater`
control over the UI of a saved site or web app on a mobile device.
It's linked to from the HTML as follows:
@@ -80,15 +87,18 @@ It's linked to from the HTML as follows:
<link rel="manifest" href="site.webmanifest">
```
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.
You should fill this file out with [more information about your site or application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
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. You
should fill this file out with [more information about your site or
application](https://developer.mozilla.org/en-US/docs/Web/Manifest)
### Favicons and Touch Icon
The shortcut icons should be put in the root directory of your site. `favicon.ico`
is automatically picked up by browsers if it's placed in the root. HTML5
Boilerplate comes with a default set of icons (include favicon and one Apple
Touch Icon) that you can use as a baseline to create your own.
The shortcut icons should be put in the root directory of your site.
`favicon.ico` is automatically picked up by browsers if it's placed in the root.
HTML5 Boilerplate comes with a default set of icons (include favicon and one
Apple Touch Icon) that you can use as a baseline to create your own.
Please refer to the more detailed description in the [Extend section](extend.md)
of these docs.
@@ -96,28 +106,31 @@ of these docs.
### The Content Area
The central part of the boilerplate template is pretty much empty. This is
intentional, in order to make the boilerplate suitable for both web page and
web app development.
intentional, in order to make the boilerplate suitable for both web page and web
app development.
### Modernizr
HTML5 Boilerplate uses a custom build of Modernizr.
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes to
the `html` element based on the results of feature test and which ensures that
all browsers can make use of HTML5 elements (as it includes the HTML5 Shiv).
This allows you to target parts of your CSS and JavaScript based on the
[Modernizr](https://modernizr.com/) is a JavaScript library which adds classes
to the `html` element based on the results of feature test and which ensures
that all browsers can make use of HTML5 elements (as it includes the HTML5
Shiv). This allows you to target parts of your CSS and JavaScript based on the
features supported by a browser.
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
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).
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 [Modernizr command line
utility](https://www.npmjs.com/package/modernizr-cli).
### What About Polyfills?
If you need to include [polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill)
in your project, you must make sure those load before any other JavaScript. If you're
using a polyfill CDN service, like [polyfill.io](https://polyfill.io/),
just put it before the other scripts in the bottom of the page:
If you need to include
[polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill) in your
project, you must make sure those load before any other JavaScript. If you're
using a polyfill CDN service, like [polyfill.io](https://polyfill.io/), just put
it before the other scripts in the bottom of the page:
```html
<script src="js/vendor/modernizr-3.10.0.min.js"></script>
@@ -130,62 +143,68 @@ just put it before the other scripts in the bottom of the page:
```
If you like to just include the polyfills yourself, you could include them in
`js/plugins.js`. When you have a bunch of polyfills to load in, you could
also create a `polyfills.js` file in the `js/vendor` directory or include the files
individually and combine them using a build tool. Always ensure that the polyfills
are all loaded before any other JavaScript.
`js/plugins.js`. When you have a bunch of polyfills to load in, you could also
create a `polyfills.js` file in the `js/vendor` directory or include the files
individually and combine them using a build tool. Always ensure that the
polyfills are all loaded before any other JavaScript.
There are some misconceptions about Modernizr and polyfills. It's important
to understand that Modernizr just handles feature checking, not polyfilling
itself. The only thing Modernizr does regarding polyfills is that the team
maintains [a huge list of cross Browser polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
There are some misconceptions about Modernizr and polyfills. It's important to
understand that Modernizr just handles feature checking, not polyfilling itself.
The only thing Modernizr does regarding polyfills is that the team maintains [a
huge list of cross Browser
polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
### jQuery CDN for jQuery
The jQuery CDN version of the jQuery JavaScript library is referenced towards
the bottom of the page. A local fallback of jQuery is included for rare instances
when the CDN version might not be available, and to facilitate offline
the bottom of the page. A local fallback of jQuery is included for rare
instances when the CDN version might not be available, and to facilitate offline
development.
The jQuery CDN version was chosen over other potential candidates
([like Google's Hosted Libraries](https://developers.google.com/speed/libraries/))
The jQuery CDN version was chosen over other potential candidates ([like
Google's Hosted Libraries](https://developers.google.com/speed/libraries/))
because it's fast ([comparable or faster than Google by some
measures](https://www.cdnperf.com/#jsdelivr,cdnjs,google,yandex,microsoft,jquery,bootstrapcdn/https/90))
and, (unlike Google's CDN) is available to China's hundreds of millions of internet users.
For many years we [chose](https://github.com/h5bp/html5-boilerplate/issues/1191)
the Google Hosted version over the jQuery CDN because it was available
over HTTPS (the jQuery CDN was not,) and it offered a better chance of
hitting the cache lottery owing to the popularity of the Google CDN.
The first issue is no longer valid and the second is far outweighed by
being able to serve jQuery to users in China.
and, (unlike Google's CDN) is available to China's hundreds of millions of
internet users. For many years we
[chose](https://github.com/h5bp/html5-boilerplate/issues/1191) the Google Hosted
version over the jQuery CDN because it was available over HTTPS (the jQuery CDN
was not,) and it offered a better chance of hitting the cache lottery owing to
the popularity of the Google CDN. The first issue is no longer valid and the
second is far outweighed by being able to serve jQuery to users in China.
While the jQuery CDN is a strong default solution your site or application may
require a different configuration. Testing your site with services like
[WebPageTest](https://www.webpagetest.org/) and browser tools like
[PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) will help you examine the real
world performance of your site and can show where you can optimize your specific
site or application.
[WebPageTest](https://www.webpagetest.org/) and browser tools like [PageSpeed
Insights](https://developers.google.com/speed/pagespeed/insights/) will help you
examine the real world performance of your site and can show where you can
optimize your specific site or application.
### Google Universal Analytics Tracking Code
Finally, an optimized version of the Google Universal Analytics tracking code is
included.
We use `analytics.js` rather than the newer `gtag.js` as
[it's faster and supports tasks and plugins](https://github.com/philipwalton/analyticsjs-boilerplate/issues/19#issuecomment-333714370)
We use `analytics.js` rather than the newer `gtag.js` as [it's faster and
supports tasks and
plugins](https://github.com/philipwalton/analyticsjs-boilerplate/issues/19#issuecomment-333714370)
Starting with version 8 we, by default, [anonymize IP addresses](href="https://support.google.com/analytics/answer/2763052?hl=en).
By default Google Analytics records the full IP address of a user visiting the site, but
that full IP address is never available to the Google Analytics property admin.
By anonymizing the IP address you can make your site more GDPR-compliant as a
full IP address can be defined as PII (personally identifiable information.)
Starting with version 8 we, by default, [anonymize IP
addresses](href="https://support.google.com/analytics/answer/2763052?hl=en). By
default Google Analytics records the full IP address of a user visiting the
site, but that full IP address is never available to the Google Analytics
property admin. By anonymizing the IP address you can make your site more
GDPR-compliant as a full IP address can be defined as PII (personally
identifiable information.)
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).
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).
Google recommends that this script be placed at the top of the page.
Factors to consider: if you place this script at the top of the page, you’ll
be able to count users who don’t fully load the page, and you’ll incur the max
number of simultaneous connections of the browser.
Google recommends that this script be placed at the top of the page. Factors to
consider: if you place this script at the top of the page, you’ll be able to
count users who don’t fully load the page, and you’ll incur the max number of
simultaneous connections of the browser.
Further information:
@@ -193,9 +212,9 @@ Further information:
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
**N.B.** The Google Analytics snippet is included by default mainly
because Google Analytics is [currently one of the most popular tracking
**N.B.** The Google Analytics snippet is included by default mainly because
Google Analytics is [currently one of the most popular tracking
solutions](https://trends.builtwith.com/analytics/Google-Analytics) out there.
However, its usage isn't set in stone, and you SHOULD consider exploring the
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software)
and use whatever suits your needs best.
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software) and
use whatever suits your needs best.

22
src/doc/js.md
View File

@@ -7,22 +7,22 @@ Information about the default JavaScript included in the project.
## main.js
This file can be used to contain or reference your site/app JavaScript code.
If you're working on something more advanced you might replace this file
entirely. That's cool.
This file can be used to contain or reference your site/app JavaScript code. If
you're working on something more advanced you might replace this file entirely.
That's cool.
## plugins.js
This file can be used to contain all your plugins, such as jQuery plugins and
other 3rd party scripts for a simple site.
One approach is to put jQuery plugins inside of a `(function($){ ...
})(jQuery);` closure to make sure they're in the jQuery namespace safety
blanket. Read more about [jQuery plugin authoring](https://learn.jquery.com/plugins/).
One approach is to put jQuery plugins inside of a `(function($){ ...})(jQuery);`
closure to make sure they're in the jQuery namespace safety blanket. Read more
about [jQuery plugin authoring](https://learn.jquery.com/plugins/).
By default the `plugins.js` file contains a small script to avoid `console`
errors in browsers that lack a `console`. The script will make sure that, if
a console method isn't available, that method will have the value of empty
errors in browsers that lack a `console`. The script will make sure that, if a
console method isn't available, that method will have the value of empty
function, thus, preventing the browser from throwing an error.
## vendor
@@ -30,6 +30,6 @@ function, thus, preventing the browser from throwing an error.
This directory can be used to contain all 3rd party library code.
Minified versions of the latest jQuery and Modernizr libraries are included by
default. You may wish to create your own [custom Modernizr
build with the online builder](https://modernizr.com/download/) or [command
line tool](https://modernizr.com/docs#command-line-config).
default. You may wish to create your own [custom Modernizr build with the online
builder](https://modernizr.com/download/) or [command line
tool](https://modernizr.com/docs#command-line-config).

21
src/doc/usage.md
View File

@@ -27,7 +27,7 @@ HTML5 Boilerplate is a starting point, not a destination.
A basic HTML5 Boilerplate site initially looks something like this:
``` bash
```
.
├── css
│ ├── main.css
@@ -80,8 +80,9 @@ refer to the [Apache Server Configs
repository](https://github.com/h5bp/server-configs-apache).
Host your site on a server other than Apache? You're likely to find the
corresponding server configs project listed in our [Server Configs
](https://github.com/h5bp/server-configs/blob/master/README.md) repository.
corresponding server configs project listed in our [Server
Configs](https://github.com/h5bp/server-configs/blob/master/README.md)
repository.
### 404.html
@@ -91,14 +92,14 @@ A helpful custom 404 to get you started.
This file contains all settings regarding custom tiles for IE11 and Edge.
For more info on this topic, please refer to
[Microsoft's Docs](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
For more info on this topic, please refer to [Microsoft's
Docs](https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)).
### .editorconfig
The `.editorconfig` file is provided in order to encourage and help you and
your team to maintain consistent coding styles between different
editors and IDEs. [Read more about the `.editorconfig` file](misc.md#editorconfig).
The `.editorconfig` file is provided in order to encourage and help you and your
team to maintain consistent coding styles between different editors and IDEs.
[Read more about the `.editorconfig` file](misc.md#editorconfig).
### index.html
@@ -123,8 +124,8 @@ Edit this file to include any pages you need hidden from search engines.
### Icons
Replace the default `favicon.ico`, `tile.png`, `tile-wide.png` and Apple
Touch Icon with your own.
Replace the default `favicon.ico`, `tile.png`, `tile-wide.png` and Apple Touch
Icon with your own.
If you want to use different Apple Touch Icons for different resolutions please
refer to the [according documentation](extend.md#apple-touch-icons).