Skip to content

Commit

Permalink
Merge pull request #2476 from delitescere/patch-1
Browse files Browse the repository at this point in the history 
Update html.md to tidy up link markdown
  • Loading branch information
@roblarsen
roblarsen authored Mar 5, 2021
2 parents cbb14e1 + 657b043 commit 388ea6e
Show file tree
Hide file tree
Showing 2 changed files with 78 additions and 86 deletions.
82 changes: 39 additions & 43 deletions dist/doc/html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,12 @@ to the `lang` 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://html.spec.whatwg.org/multipage/semantics.html#charset)
within the
[first 1024 bytes of the document](https://html.spec.whatwg.org/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)
potential
[encoding-related security issue](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
in Internet Explorer.

### Meta Description
Expand All @@ -49,27 +49,26 @@ results.
<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.
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.

```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
can do so with additional viewport parameters.
[Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) for
details.

### Open Graph Metadata
Expand All @@ -81,7 +80,7 @@ that define the details of your site. The required attributes define the title,
preview image, URL, and [type](https://ogp.me/#types) (e.g., video, music,
website, article).

``` html
```html
<meta property="og:title" content="">
<meta property="og:type" content="">
<meta property="og:url" content="">
Expand All @@ -96,7 +95,7 @@ To see a working example, the following is the open graph metadata for the HTML5
Boilerplate site. In addition to the required fields we add `og:description` to
describe the site in more detail.

``` html
```html
<meta property="og:url" content="https://html5boilerplate.com/">
<meta property="og:title" content="HTML5 ★ BOILERPLATE">
<meta property="og:type" content="website">
Expand All @@ -110,7 +109,7 @@ 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`
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:
Expand All @@ -122,8 +121,8 @@ It's linked to from the HTML as follows:
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)
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

Expand Down Expand Up @@ -153,8 +152,8 @@ 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).
and the
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).

### What About Polyfills?

Expand All @@ -178,9 +177,8 @@ 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).
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

Expand All @@ -202,7 +200,7 @@ to the `index.html` manually.

To load jQuery from a CDN with a local fallback you can use the following:

``` html
```html
<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-3.5.1.min.js"><\/script>')</script>
```
Expand All @@ -212,40 +210,38 @@ To load jQuery from a CDN with a local fallback you can use the following:
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.0.0 we, by default, [anonymize IP
addresses](https://support.google.com/analytics/answer/2763052). By
default Google Analytics records the full IP address of a user visiting the
Starting with version 8.0.0 we, by default,
[anonymize IP addresses](https://support.google.com/analytics/answer/2763052).
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.

Please be aware that while Google [states that it is fully GDPR compliant](https://privacy.google.com/businesses/compliance/),
Please be aware that while Google
[states that it is fully GDPR compliant](https://privacy.google.com/businesses/compliance/),
it is still possible to use analytics to violate GDPR.

Further information:

* [Introduction to
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Introduction to Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
* [Privacy Controls in Google Analytics](https://support.google.com/analytics/answer/9019185)

**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.
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.
82 changes: 39 additions & 43 deletions src/doc/html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,12 @@ to the `lang` 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://html.spec.whatwg.org/multipage/semantics.html#charset)
within the
[first 1024 bytes of the document](https://html.spec.whatwg.org/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)
potential
[encoding-related security issue](https://code.google.com/archive/p/doctype-mirror/wikis/ArticleUtf7.wiki)
in Internet Explorer.

### Meta Description
Expand All @@ -49,27 +49,26 @@ results.
<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.
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.

```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
can do so with additional viewport parameters.
[Check the WebKit blog](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) for
details.

### Open Graph Metadata
Expand All @@ -81,7 +80,7 @@ that define the details of your site. The required attributes define the title,
preview image, URL, and [type](https://ogp.me/#types) (e.g., video, music,
website, article).

``` html
```html
<meta property="og:title" content="">
<meta property="og:type" content="">
<meta property="og:url" content="">
Expand All @@ -96,7 +95,7 @@ To see a working example, the following is the open graph metadata for the HTML5
Boilerplate site. In addition to the required fields we add `og:description` to
describe the site in more detail.

``` html
```html
<meta property="og:url" content="https://html5boilerplate.com/">
<meta property="og:title" content="HTML5 ★ BOILERPLATE">
<meta property="og:type" content="website">
Expand All @@ -110,7 +109,7 @@ 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`
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:
Expand All @@ -122,8 +121,8 @@ It's linked to from the HTML as follows:
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)
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

Expand Down Expand Up @@ -153,8 +152,8 @@ 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).
and the
[Modernizr command line utility](https://www.npmjs.com/package/modernizr-cli).

### What About Polyfills?

Expand All @@ -178,9 +177,8 @@ 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).
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

Expand All @@ -202,7 +200,7 @@ to the `index.html` manually.

To load jQuery from a CDN with a local fallback you can use the following:

``` html
```html
<script src="https://code.jquery.com/jquery-3.5.1.min.js" integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0=" crossorigin="anonymous"></script>
<script>window.jQuery || document.write('<script src="js/vendor/jquery-3.5.1.min.js"><\/script>')</script>
```
Expand All @@ -212,40 +210,38 @@ To load jQuery from a CDN with a local fallback you can use the following:
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.0.0 we, by default, [anonymize IP
addresses](https://support.google.com/analytics/answer/2763052). By
default Google Analytics records the full IP address of a user visiting the
Starting with version 8.0.0 we, by default,
[anonymize IP addresses](https://support.google.com/analytics/answer/2763052).
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.

Please be aware that while Google [states that it is fully GDPR compliant](https://privacy.google.com/businesses/compliance/),
Please be aware that while Google
[states that it is fully GDPR compliant](https://privacy.google.com/businesses/compliance/),
it is still possible to use analytics to violate GDPR.

Further information:

* [Introduction to
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Introduction to Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
* [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
* [Privacy Controls in Google Analytics](https://support.google.com/analytics/answer/9019185)

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

0 comments on commit 388ea6e

Please sign in to comment.