Skip to content

Commit

Permalink
Docs updated
Browse files Browse the repository at this point in the history
  • Loading branch information
@roblarsen
roblarsen committed Aug 1, 2017
1 parent f91a925 commit 0d7fb21
Show file tree
Hide file tree
Showing 9 changed files with 153 additions and 119 deletions.
77 changes: 48 additions & 29 deletions dist/.gitattributes
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,45 @@
# Note that binary is a macro for -text -diff.
######################################################################

## AUTO-DETECT - Handle line endings automatically for files detected
## as text and leave all files detected as binary untouched.
## This will handle all files NOT defined below.
## AUTO-DETECT
## Handle line endings automatically for files detected as
## text and leave all files detected as binary untouched.
## This will handle all files NOT defined below.
* text=auto

## SOURCE CODE
*.bat text
*.coffee text
*.css text
*.htm text
*.html text
*.inc text
*.ini text
*.js text
*.jsx text
*.json text
*.less text
*.php text
*.pl text
*.py text
*.rb text
*.sass text
*.scm text
*.scss text
*.sh text
*.sql text
*.styl text
*.ts text
*.xml text
*.xhtml text
*.bat text eol=crlf
*.coffee text
*.css text
*.htm text
*.html text
*.inc text
*.ini text
*.js text
*.json text
*.jsx text
*.less text
*.od text
*.onlydata text
*.php text
*.pl text
*.py text
*.rb text
*.sass text
*.scm text
*.scss text
*.sh text eol=lf
*.sql text
*.styl text
*.tag text
*.ts text
*.tsx text
*.xml text
*.xhtml text

## DOCKER
*.dockerignore text
Dockerfile text

## DOCUMENTATION
*.markdown text
Expand All @@ -55,6 +64,8 @@ CHANGELOG text
CHANGES text
CONTRIBUTING text
COPYING text
copyright text
*COPYRIGHT* text
INSTALL text
license text
LICENSE text
Expand All @@ -73,12 +84,16 @@ TODO text
*.jade text
*.latte text
*.mustache text
*.njk text
*.phtml text
*.tmpl text
*.tpl text
*.twig text

## LINTERS
.csslintrc text
.eslintrc text
.htmlhintrc text
.jscsrc text
.jshintrc text
.jshintignore text
Expand All @@ -89,6 +104,7 @@ TODO text
*.cnf text
*.conf text
*.config text
.browserslistrc text
.editorconfig text
.gitattributes text
.gitconfig text
Expand All @@ -97,12 +113,13 @@ TODO text
*.npmignore text
*.yaml text
*.yml text
browserslist text
Makefile text
makefile text

## HEROKU
Procfile text
.slugignore text
Procfile text
.slugignore text

## GRAPHICS
*.ai binary
Expand Down Expand Up @@ -150,13 +167,15 @@ Procfile text
*.mp4 binary
*.mpeg binary
*.mpg binary
*.ogv binary
*.swc binary
*.swf binary
*.webm binary

## ARCHIVES
*.7z binary
*.gz binary
*.jar binary
*.rar binary
*.tar binary
*.zip binary
Expand Down
6 changes: 6 additions & 0 deletions dist/doc/TOC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,5 +25,11 @@ 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.
* [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)
* [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)
* [Ant Build Script](https://github.com/h5bp/ant-build-script) — Apache
Ant based build script.
5 changes: 5 additions & 0 deletions dist/doc/css.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ See also:
accessibility](https://snook.ca/archives/html_and_css/hiding-content-for-accessibility)
* [HTML5 Boilerplate - Issue #194](https://github.com/h5bp/html5-boilerplate/issues/194).

__N.B.__ [The visuallyhidden class can be an accessibility issue for users using high contrast modes.](https://www.paciellogroup.com/blog/2012/08/notes-on-accessible-css-image-sprites/)

>Use JavaScript to detect when images are disabled and remove the CSS visually hidden display state of the text alternative.
Use JavaScript to detect when Windows high contrast mode is enabled and remove the CSS visually hidden display state of the text alternative.

#### `.invisible`

The `invisible` class can be added to any element that you want to hide
Expand Down
50 changes: 17 additions & 33 deletions dist/doc/extend.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,6 @@ not everything fits with everyone's needs.

## App Stores

### Install a Chrome Web Store app

Users can install a Chrome app directly from your website, as long as
the app and site have been associated via Google's Webmaster Tools.
Read more on [Chrome Web Store's Inline Installation
docs](https://developer.chrome.com/webstore/inline_installation).

```html
<link rel="chrome-webstore-item" href="https://chrome.google.com/webstore/detail/APP_ID">
```

### Smart App Banners in iOS 6+ Safari

Stop bothering everyone with gross modals advertising your entry in the
Expand Down Expand Up @@ -280,10 +269,10 @@ mouse over your Pinned Site's icon.
If the site should go to a specific URL when it is pinned (such as the
homepage), enter it here. One idea is to send it to a special URL so you can
track the number of pinned users, like so:
`http://www.example.com/index.html?pinned=true`
`https://www.example.com/index.html?pinned=true`

```html
<meta name="msapplication-starturl" content="http://www.example.com/index.html?pinned=true">
<meta name="msapplication-starturl" content="https://www.example.com/index.html?pinned=true">
```

### Recolor IE's controls manually for a Pinned Site
Expand Down Expand Up @@ -342,7 +331,7 @@ or one of a predefined list of glyphs.
* [Available badge values](https://msdn.microsoft.com/en-us/library/ie/br212849.aspx)

```html
<meta name="msapplication-badge" value="frequency=NUMBER_IN_MINUTES;polling-uri=http://www.example.com/path/to/file.xml">
<meta name="msapplication-badge" value="frequency=NUMBER_IN_MINUTES;polling-uri=https://www.example.com/path/to/file.xml">
```

### Disable link highlighting upon tap in IE10
Expand Down Expand Up @@ -372,7 +361,7 @@ Submit it to search engine tool:
OR
Insert the following line anywhere in your robots.txt file, specifying the path to your sitemap:
```
Sitemap: http://example.com/sitemap_location.xml
Sitemap: https://example.com/sitemap_location.xml
```

### Hide pages from search engines
Expand Down Expand Up @@ -426,10 +415,6 @@ plugin](https://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plug
page) by [implementing X-Robots-tag
headers](https://github.com/h5bp/html5-boilerplate/issues/804).

* Screen readers currently have less-than-stellar support for HTML5 but the JS
script [accessifyhtml5.js](https://github.com/yatil/accessifyhtml5.js) can
help increase accessibility by adding ARIA roles to HTML5 elements.


## News Feeds

Expand Down Expand Up @@ -488,10 +473,10 @@ registration to Facebook).

```html
<meta property="fb:app_id" content="123456789">
<meta property="og:url" content="http://www.example.com/path/to/page.html">
<meta property="og:url" content="https://www.example.com/path/to/page.html">
<meta property="og:type" content="website">
<meta property="og:title" content="">
<meta property="og:image" content="http://www.example.com/path/to/image.jpg">
<meta property="og:image" content="https://www.example.com/path/to/image.jpg">
<meta property="og:description" content="">
<meta property="og:site_name" content="">
<meta property="article:author" content="">
Expand All @@ -512,10 +497,10 @@ your markup with the [Card validator](https://cards-dev.twitter.com/validator)
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@site_account">
<meta name="twitter:creator" content="@individual_account">
<meta name="twitter:url" content="http://www.example.com/path/to/page.html">
<meta name="twitter:url" content="https://www.example.com/path/to/page.html">
<meta name="twitter:title" content="">
<meta name="twitter:description" content="">
<meta name="twitter:image" content="http://www.example.com/path/to/image.jpg">
<meta name="twitter:image" content="https://www.example.com/path/to/image.jpg">
```

### Google+ / Schema.org
Expand Down Expand Up @@ -551,8 +536,8 @@ top `html` tag.

Signal to search engines and others "Use this URL for this page!" Useful when
parameters after a `#` or `?` is used to control the display state of a page.
`http://www.example.com/cart.html?shopping-cart-open=true` can be indexed as
the cleaner, more accurate `http://www.example.com/cart.html`.
`https://www.example.com/cart.html?shopping-cart-open=true` can be indexed as
the cleaner, more accurate `https://www.example.com/cart.html`.

```html
<link rel="canonical" href="">
Expand All @@ -579,12 +564,12 @@ 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="http://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.:

`<link rel="canonical" href="http://www.example.com/page.html">`
`<link rel="canonical" href="https://www.example.com/page.html">`

For more information please see:

Expand All @@ -601,15 +586,15 @@ added to the Home Screen on iOS:
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
```html
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
```

* You can use `apple-mobile-web-app-title` to add a specific sites name for the
Home Screen icon. This works since iOS 6.

```html
```html
<meta name="apple-mobile-web-app-title" content="">
```

Expand Down Expand Up @@ -642,11 +627,11 @@ Displays meaning:
More information about the displays of iOS devices can be found
[here](https://en.wikipedia.org/wiki/List_of_iOS_devices#Display).

In most cases, one `180×180px` touch icon named `apple-touch-icon.png`
In most cases, one `180×180px` touch icon named `icon.png`
and including:

```html
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<link rel="apple-touch-icon" href="icon.png">
```

in the `<head>` of the page is enough. If you use art-direction and/or
Expand Down Expand Up @@ -705,5 +690,4 @@ 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)
and [Firefox OS 2.1+](https://twitter.com/ahmednefzaoui/status/492344698493997057).
for Android Lollipop](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android).
23 changes: 12 additions & 11 deletions dist/doc/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,34 +12,35 @@ table of contents](TOC.md)
* [Where can I get help with support
questions?](#where-can-i-get-help-with-support-questions)

--

---

### Why is the Google Analytics code at the bottom? Google recommends it be placed in the `<head>`.

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.
However, having the code at the bottom of the page [helps improve
performance](https://stevesouders.com/efws/inline-scripts-bottom.php).

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

### How can I integrate [Bootstrap](https://getbootstrap.com/) with HTML5 Boilerplate?

One simple way is to use [Initializr](http://www.initializr.com/) and create a
custom build that includes both HTML5 Boilerplate and
[Bootstrap](https://getbootstrap.com/).

Read more about how [HTML5 Boilerplate and Bootstrap complement each
Here's Nicolas Gallagher writing about how [HTML5 Boilerplate and Bootstrap complement each
other](https://www.quora.com/Is-Bootstrap-a-complement-or-an-alternative-to-HTML5-Boilerplate-or-viceversa/answer/Nicolas-Gallagher).


### Do I need to upgrade my site each time a new version of HTML5 Boilerplate is released?

No, same 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?

Please ask for help on
Expand Down
Loading

0 comments on commit 0d7fb21

Please sign in to comment.