reportir 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.gitignore +9 -0
- data/.rspec +2 -0
- data/.travis.yml +4 -0
- data/CODE_OF_CONDUCT.md +13 -0
- data/Gemfile +4 -0
- data/LICENSE.txt +21 -0
- data/README.md +81 -0
- data/Rakefile +6 -0
- data/bin/console +14 -0
- data/bin/setup +7 -0
- data/lib/reportir/static_site_template/.editorconfig +13 -0
- data/lib/reportir/static_site_template/.gitattributes +1 -0
- data/lib/reportir/static_site_template/.gitignore +2 -0
- data/lib/reportir/static_site_template/.htaccess +984 -0
- data/lib/reportir/static_site_template/404.html +60 -0
- data/lib/reportir/static_site_template/LICENSE.txt +19 -0
- data/lib/reportir/static_site_template/apple-touch-icon.png +0 -0
- data/lib/reportir/static_site_template/browserconfig.xml +12 -0
- data/lib/reportir/static_site_template/crossdomain.xml +15 -0
- data/lib/reportir/static_site_template/css/font/FontAwesome.otf +0 -0
- data/lib/reportir/static_site_template/css/font/fontawesome-webfont.eot +0 -0
- data/lib/reportir/static_site_template/css/font/fontawesome-webfont.svg +284 -0
- data/lib/reportir/static_site_template/css/font/fontawesome-webfont.ttf +0 -0
- data/lib/reportir/static_site_template/css/font/fontawesome-webfont.woff +0 -0
- data/lib/reportir/static_site_template/css/main.css +348 -0
- data/lib/reportir/static_site_template/css/normalize.css +424 -0
- data/lib/reportir/static_site_template/css/vendor/bootstrap.min.css +5 -0
- data/lib/reportir/static_site_template/css/vendor/font-awesome.min.css +33 -0
- data/lib/reportir/static_site_template/doc/TOC.md +29 -0
- data/lib/reportir/static_site_template/doc/css.md +162 -0
- data/lib/reportir/static_site_template/doc/extend.md +663 -0
- data/lib/reportir/static_site_template/doc/faq.md +62 -0
- data/lib/reportir/static_site_template/doc/html.md +223 -0
- data/lib/reportir/static_site_template/doc/js.md +37 -0
- data/lib/reportir/static_site_template/doc/misc.md +175 -0
- data/lib/reportir/static_site_template/doc/usage.md +130 -0
- data/lib/reportir/static_site_template/favicon.ico +0 -0
- data/lib/reportir/static_site_template/humans.txt +15 -0
- data/lib/reportir/static_site_template/img/.gitignore +0 -0
- data/lib/reportir/static_site_template/img/pagination.png +0 -0
- data/lib/reportir/static_site_template/index.html +78 -0
- data/lib/reportir/static_site_template/js/main.js +0 -0
- data/lib/reportir/static_site_template/js/plugins.js +24 -0
- data/lib/reportir/static_site_template/js/vendor/bootstrap.min.js +7 -0
- data/lib/reportir/static_site_template/js/vendor/jquery-1.11.3.min.js +6 -0
- data/lib/reportir/static_site_template/js/vendor/jquery.slides.min.js +7 -0
- data/lib/reportir/static_site_template/js/vendor/modernizr-2.8.3.min.js +4 -0
- data/lib/reportir/static_site_template/robots.txt +5 -0
- data/lib/reportir/static_site_template/tile-wide.png +0 -0
- data/lib/reportir/static_site_template/tile.png +0 -0
- data/lib/reportir/version.rb +3 -0
- data/lib/reportir.rb +109 -0
- data/reportir.gemspec +29 -0
- metadata +196 -0
@@ -0,0 +1,62 @@
|
|
1
|
+
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
|
2
|
+
table of contents](TOC.md)
|
3
|
+
|
4
|
+
# Frequently asked questions
|
5
|
+
|
6
|
+
* [Why don't you automatically load the latest version of jQuery from the Google
|
7
|
+
CDN?](#why-dont-you-automatically-load-the-latest-version-of-jquery-from-the-google-cdn)
|
8
|
+
* [Why is the Google Analytics code at the bottom? Google recommends it be
|
9
|
+
placed in the `<head>`.](#why-is-the-google-analytics-code-at-the-bottom-google-recommends-it-be-placed-in-the-head)
|
10
|
+
* [How can I integrate Bootstrap with HTML5
|
11
|
+
Boilerplate?](#how-can-i-integrate-bootstrap-with-html5-boilerplate)
|
12
|
+
* [Do I need to upgrade my site each time a new version of HTML5 Boilerplate is
|
13
|
+
released?](#do-i-need-to-upgrade-my-site-each-time-a-new-version-of-html5-boilerplate-is-released)
|
14
|
+
* [Where can I get help with support
|
15
|
+
questions?](#where-can-i-get-help-with-support-questions)
|
16
|
+
|
17
|
+
--
|
18
|
+
|
19
|
+
### Why don't you automatically load the latest version of jQuery from the Google CDN?
|
20
|
+
|
21
|
+
The [file](https://ajax.googleapis.com/ajax/libs/jquery/1/jquery.js) to which
|
22
|
+
the Google [CDN](https://en.wikipedia.org/wiki/Content_delivery_network) points
|
23
|
+
to is [no longer updated and will stay locked at version `1.11.1` in order to
|
24
|
+
prevent inadvertent web
|
25
|
+
breakage](http://blog.jquery.com/2014/07/03/dont-use-jquery-latest-js/).
|
26
|
+
|
27
|
+
In general, version updating should be an intentional decision! You shouldn't
|
28
|
+
include a URL that will always point to the latest version, as that version:
|
29
|
+
|
30
|
+
* may not be compatible with the existing plugins/code on the site
|
31
|
+
* will have a very short cache time compare to the specific version,
|
32
|
+
which means that users won't get the benefits of long-term caching
|
33
|
+
|
34
|
+
### Why is the Google Analytics code at the bottom? Google recommends it be placed in the `<head>`.
|
35
|
+
|
36
|
+
The main advantage of placing it in the `<head>` is that you will track the
|
37
|
+
user's `pageview` even if they leave the page before it has been fully loaded.
|
38
|
+
However, having the code at the bottom of the page [helps improve
|
39
|
+
performance](https://stevesouders.com/efws/inline-scripts-bottom.php).
|
40
|
+
|
41
|
+
|
42
|
+
### How can I integrate [Bootstrap](http://getbootstrap.com/) with HTML5 Boilerplate?
|
43
|
+
|
44
|
+
One simple way is to use [Initializr](http://www.initializr.com/) and create a
|
45
|
+
custom build that includes both HTML5 Boilerplate and
|
46
|
+
[Bootstrap](http://getbootstrap.com/).
|
47
|
+
|
48
|
+
Read more about how [HTML5 Boilerplate and Bootstrap complement each
|
49
|
+
other](https://www.quora.com/Is-Bootstrap-a-complement-or-an-alternative-to-HTML5-Boilerplate-or-viceversa/answer/Nicolas-Gallagher).
|
50
|
+
|
51
|
+
|
52
|
+
### Do I need to upgrade my site each time a new version of HTML5 Boilerplate is released?
|
53
|
+
|
54
|
+
No, same as you don't normally replace the foundation of a house once it
|
55
|
+
was built. However, there is nothing stopping you from trying to work in the
|
56
|
+
latest changes, but you'll have to assess the costs/benefits of doing so.
|
57
|
+
|
58
|
+
|
59
|
+
### Where can I get help with support questions?
|
60
|
+
|
61
|
+
Please ask for help on
|
62
|
+
[StackOverflow](https://stackoverflow.com/questions/tagged/html5boilerplate).
|
@@ -0,0 +1,223 @@
|
|
1
|
+
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
|
2
|
+
table of contents](TOC.md)
|
3
|
+
|
4
|
+
# The HTML
|
5
|
+
|
6
|
+
By default, HTML5 Boilerplate provides two `html` pages:
|
7
|
+
|
8
|
+
* [`index.html`](#indexhtml) - a default HTML skeleton that should form the
|
9
|
+
basis of all pages on your website
|
10
|
+
* [`404.html`](#404html) - a placeholder 404 error page
|
11
|
+
|
12
|
+
|
13
|
+
## `index.html`
|
14
|
+
|
15
|
+
|
16
|
+
### The `no-js` class
|
17
|
+
|
18
|
+
The `no-js` class is provided in order to allow you to more easily and
|
19
|
+
explicitly add custom styles based on whether JavaScript is disabled
|
20
|
+
(`.no-js`) or enabled (`.js`). Using this technique also helps [avoid the
|
21
|
+
FOUC](https://www.paulirish.com/2009/avoiding-the-fouc-v3/).
|
22
|
+
|
23
|
+
|
24
|
+
## Language attribute
|
25
|
+
|
26
|
+
Please consider specifying the language of your content by adding the `lang`
|
27
|
+
attribute to `<html>` as in this example:
|
28
|
+
|
29
|
+
```html
|
30
|
+
<html class="no-js" lang="en">
|
31
|
+
```
|
32
|
+
|
33
|
+
### The order of the `<title>` and `<meta>` tags
|
34
|
+
|
35
|
+
The order in which the `<title>` and the `<meta>` tags are specified is
|
36
|
+
important because:
|
37
|
+
|
38
|
+
1) the charset declaration (`<meta charset="utf-8">`):
|
39
|
+
|
40
|
+
* must be included completely within the [first 1024 bytes of the
|
41
|
+
document](https://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset)
|
42
|
+
|
43
|
+
* should be specified as early as possible (before any content that could
|
44
|
+
be controlled by an attacker, such as a `<title>` element) in order to
|
45
|
+
avoid a potential [encoding-related security
|
46
|
+
issue](https://code.google.com/p/doctype-mirror/wiki/ArticleUtf7) in
|
47
|
+
Internet Explorer
|
48
|
+
|
49
|
+
2) the meta tag for compatibility mode
|
50
|
+
(`<meta http-equiv="x-ua-compatible" content="ie=edge">`):
|
51
|
+
|
52
|
+
* [needs to be included before all other tags except for the `<title>` and
|
53
|
+
the other `<meta>`
|
54
|
+
tags](https://msdn.microsoft.com/en-us/library/cc288325.aspx)
|
55
|
+
|
56
|
+
|
57
|
+
### `x-ua-compatible`
|
58
|
+
|
59
|
+
Internet Explorer 8/9/10 support [document compatibility
|
60
|
+
modes](https://msdn.microsoft.com/en-us/library/cc288325.aspx) that affect the
|
61
|
+
way webpages are interpreted and displayed. Because of this, even if your site's
|
62
|
+
visitor is using, let's say, Internet Explorer 9, it's possible that IE will not
|
63
|
+
use the latest rendering engine, and instead, decide to render your page using
|
64
|
+
the Internet Explorer 5.5 rendering engine.
|
65
|
+
|
66
|
+
Specifying the `x-ua-compatible` meta tag:
|
67
|
+
|
68
|
+
```html
|
69
|
+
<meta http-equiv="x-ua-compatible" content="ie=edge">
|
70
|
+
```
|
71
|
+
|
72
|
+
or sending the page with the following HTTP response header
|
73
|
+
|
74
|
+
```
|
75
|
+
X-UA-Compatible: IE=edge
|
76
|
+
```
|
77
|
+
|
78
|
+
will force Internet Explorer 8/9/10 to render the webpage in the highest
|
79
|
+
available mode in [the various cases when it may
|
80
|
+
not](https://hsivonen.fi/doctype/#ie8), and therefore, ensure that anyone
|
81
|
+
browsing your site is treated to the best possible user experience that
|
82
|
+
browser can offer.
|
83
|
+
|
84
|
+
If possible, we recommend that you remove the `meta` tag and send only the
|
85
|
+
HTTP response header as the `meta` tag will not always work if your site is
|
86
|
+
served on a non-standard port, as Internet Explorer's preference option
|
87
|
+
`Display intranet sites in Compatibility View` is checked by default.
|
88
|
+
|
89
|
+
If you are using Apache as your webserver, including the
|
90
|
+
[`.htaccess`](https://github.com/h5bp/server-configs-apache) file takes care of
|
91
|
+
the HTTP header. If you are using a different server, check out our [other
|
92
|
+
server config](https://github.com/h5bp/server-configs).
|
93
|
+
|
94
|
+
Starting with Internet Explorer 11, [document modes are
|
95
|
+
deprecated](https://msdn.microsoft.com/en-us/library/ie/bg182625.aspx#docmode).
|
96
|
+
If your business still relies on older web apps and services that were
|
97
|
+
designed for older versions of Internet Explorer, you might want to consider
|
98
|
+
enabling [Enterprise Mode](http://blogs.msdn.com/b/ie/archive/2014/04/02/stay-up-to-date-with-enterprise-mode-for-internet-explorer-11.aspx) throughout your company.
|
99
|
+
|
100
|
+
|
101
|
+
## Mobile viewport
|
102
|
+
|
103
|
+
There are a few different options that you can use with the [`viewport` meta
|
104
|
+
tag](https://docs.google.com/present/view?id=dkx3qtm_22dxsrgcf4 "Viewport and
|
105
|
+
Media Queries - The Complete Idiot's Guide"). You can find out more in [the
|
106
|
+
Apple developer docs](https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariWebContent/UsingtheViewport/UsingtheViewport.html).
|
107
|
+
HTML5 Boilerplate comes with a simple setup that strikes a good balance for general use cases.
|
108
|
+
|
109
|
+
```html
|
110
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
111
|
+
```
|
112
|
+
|
113
|
+
## Favicons and Touch Icon
|
114
|
+
|
115
|
+
The shortcut icons should be put in the root directory of your site. HTML5
|
116
|
+
Boilerplate comes with a default set of icons (include favicon and one Apple
|
117
|
+
Touch Icon) that you can use as a baseline to create your own.
|
118
|
+
|
119
|
+
Please refer to the more detailed description in the [Extend section](extend.md)
|
120
|
+
of these docs.
|
121
|
+
|
122
|
+
## Modernizr
|
123
|
+
|
124
|
+
HTML5 Boilerplate uses a custom build of Modernizr.
|
125
|
+
|
126
|
+
[Modernizr](http://modernizr.com) is a JavaScript library which adds classes to
|
127
|
+
the `html` element based on the results of feature test and which ensures that
|
128
|
+
all browsers can make use of HTML5 elements (as it includes the HTML5 Shiv).
|
129
|
+
This allows you to target parts of your CSS and JavaScript based on the
|
130
|
+
features supported by a browser.
|
131
|
+
|
132
|
+
In general, in order to keep page load times to a minimum, it's best to call
|
133
|
+
any JavaScript at the end of the page because if a script is slow to load
|
134
|
+
from an external server it may cause the whole page to hang. That said, the
|
135
|
+
Modernizr script *needs* to run *before* the browser begins rendering the page,
|
136
|
+
so that browsers lacking support for some of the new HTML5 elements are able to
|
137
|
+
handle them properly. Therefore the Modernizr script is the only JavaScript
|
138
|
+
file synchronously loaded at the top of the document.
|
139
|
+
|
140
|
+
## What about polyfills?
|
141
|
+
|
142
|
+
If you need to include [polyfills](https://remysharp.com/2010/10/08/what-is-a-polyfill)
|
143
|
+
in your project, you must make sure those load before any other JavaScript. If you're
|
144
|
+
using some polyfill CDN service, like [cdn.polyfill.io](https://cdn.polyfill.io/),
|
145
|
+
just put it before the other scripts in the bottom of the page:
|
146
|
+
|
147
|
+
```html
|
148
|
+
<script src="https://cdn.polyfill.io/v1/polyfill.min.js"></script>
|
149
|
+
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
|
150
|
+
<script>window.jQuery || document.write('<script src="js/vendor/jquery-1.11.2.min.js"><\/script>')</script>
|
151
|
+
<script src="js/plugins.js"></script>
|
152
|
+
<script src="js/main.js"></script>
|
153
|
+
</body>
|
154
|
+
```
|
155
|
+
|
156
|
+
If you like to just include the polyfills yourself, you could include them in
|
157
|
+
`js/plugins.js`. When you have a bunch of polyfills to load in, you could
|
158
|
+
also create a `polyfills.js` file in the `js/vendor` directory. Also using
|
159
|
+
this technique, make sure the polyfills are all loaded before any other
|
160
|
+
Javascript.
|
161
|
+
|
162
|
+
There are some misconceptions about Modernizr and polyfills. It's important
|
163
|
+
to understand that Modernizr just handles feature checking, not polyfilling
|
164
|
+
itself. The only thing Modernizr does regarding polyfills is that the team
|
165
|
+
maintains [a huge list of cross Browser polyfills](https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills).
|
166
|
+
|
167
|
+
## The content area
|
168
|
+
|
169
|
+
The central part of the boilerplate template is pretty much empty. This is
|
170
|
+
intentional, in order to make the boilerplate suitable for both web page and
|
171
|
+
web app development.
|
172
|
+
|
173
|
+
### Browser Upgrade Prompt
|
174
|
+
|
175
|
+
The main content area of the boilerplate includes a prompt to install an up to
|
176
|
+
date browser for users of IE 6/7. If you intended to support IE 6/7, then you
|
177
|
+
should remove the snippet of code.
|
178
|
+
|
179
|
+
### Google CDN for jQuery
|
180
|
+
|
181
|
+
The Google CDN version of the jQuery JavaScript library is referenced towards
|
182
|
+
the bottom of the page using a protocol-independent path (read more about this
|
183
|
+
in the [FAQ](faq.md)). A local fallback of jQuery is included for rare instances
|
184
|
+
when the CDN version might not be available, and to facilitate offline
|
185
|
+
development.
|
186
|
+
|
187
|
+
The Google CDN version is chosen over other [potential candidates (like the
|
188
|
+
jQuery CDN](https://jquery.com/download/#using-jquery-with-a-cdn)) because
|
189
|
+
it's fast in absolute terms and it has the best overall
|
190
|
+
[penetration](http://httparchive.org/trends.php#perGlibs) which increases the
|
191
|
+
odds of having a copy of the library in your user's browser cache.
|
192
|
+
|
193
|
+
While the Google CDN is a strong default solution your site or application may
|
194
|
+
require a different configuration. Testing your site with services like
|
195
|
+
[WebPageTest](https://www.webpagetest.org/) and browser tools like
|
196
|
+
[PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/) or
|
197
|
+
[YSlow](https://developer.yahoo.com/yslow/) will help you examine the real
|
198
|
+
world performance of your site and can show where you can optimize your specific
|
199
|
+
site or application.
|
200
|
+
|
201
|
+
|
202
|
+
### Google Universal Analytics Tracking Code
|
203
|
+
|
204
|
+
Finally, an optimized version of the Google Universal Analytics tracking code is
|
205
|
+
included. Google recommends that this script be placed at the top of the page.
|
206
|
+
Factors to consider: if you place this script at the top of the page, you’ll
|
207
|
+
be able to count users who don’t fully load the page, and you’ll incur the max
|
208
|
+
number of simultaneous connections of the browser.
|
209
|
+
|
210
|
+
Further information:
|
211
|
+
|
212
|
+
* [Optimizing the Google Universal Analytics
|
213
|
+
Snippet](https://mathiasbynens.be/notes/async-analytics-snippet#universal-analytics)
|
214
|
+
* [Introduction to
|
215
|
+
Analytics.js](https://developers.google.com/analytics/devguides/collection/analyticsjs/)
|
216
|
+
* [Google Analytics Demos & Tools](https://ga-dev-tools.appspot.com/)
|
217
|
+
|
218
|
+
**N.B.** The Google Universal Analytics snippet is included by default mainly
|
219
|
+
because Google Analytics is [currently one of the most popular tracking
|
220
|
+
solutions](https://trends.builtwith.com/analytics/Google-Analytics) out there.
|
221
|
+
However, its usage isn't set in stone, and you SHOULD consider exploring the
|
222
|
+
[alternatives](https://en.wikipedia.org/wiki/List_of_web_analytics_software)
|
223
|
+
and use whatever suits your needs best!
|
@@ -0,0 +1,37 @@
|
|
1
|
+
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
|
2
|
+
table of contents](TOC.md)
|
3
|
+
|
4
|
+
# The JavaScript
|
5
|
+
|
6
|
+
Information about the default JavaScript included in the project.
|
7
|
+
|
8
|
+
## main.js
|
9
|
+
|
10
|
+
This file can be used to contain or reference your site/app JavaScript code.
|
11
|
+
For larger projects, you can make use of a JavaScript module loader, like
|
12
|
+
[Require.js](http://requirejs.org/), to load any other scripts you need to
|
13
|
+
run.
|
14
|
+
|
15
|
+
## plugins.js
|
16
|
+
|
17
|
+
This file can be used to contain all your plugins, such as jQuery plugins and
|
18
|
+
other 3rd party scripts.
|
19
|
+
|
20
|
+
One approach is to put jQuery plugins inside of a `(function($){ ...
|
21
|
+
})(jQuery);` closure to make sure they're in the jQuery namespace safety
|
22
|
+
blanket. Read more about [jQuery plugin
|
23
|
+
authoring](https://learn.jquery.com/plugins/#Getting_Started).
|
24
|
+
|
25
|
+
By default the `plugins.js` file contains a small script to avoid `console`
|
26
|
+
errors in browsers that lack a `console`. The script will make sure that, if
|
27
|
+
a console method isn't available, that method will have the value of empty
|
28
|
+
function, thus, preventing the browser from throwing an error.
|
29
|
+
|
30
|
+
|
31
|
+
## vendor
|
32
|
+
|
33
|
+
This directory can be used to contain all 3rd party library code.
|
34
|
+
|
35
|
+
Minified versions of the latest jQuery and Modernizr libraries are included by
|
36
|
+
default. You may wish to create your own [custom Modernizr
|
37
|
+
build](http://www.modernizr.com/download/).
|
@@ -0,0 +1,175 @@
|
|
1
|
+
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
|
2
|
+
table of contents](TOC.md)
|
3
|
+
|
4
|
+
# Miscellaneous
|
5
|
+
|
6
|
+
* [.gitignore](#gitignore)
|
7
|
+
* [.editorconfig](#editorconfig)
|
8
|
+
* [Server Configuration](#server-configuration)
|
9
|
+
* [crossdomain.xml](#crossdomainxml)
|
10
|
+
* [robots.txt](#robotstxt)
|
11
|
+
* [browserconfig.xml](#browserconfigxml)
|
12
|
+
|
13
|
+
--
|
14
|
+
|
15
|
+
## .gitignore
|
16
|
+
|
17
|
+
HTML5 Boilerplate includes a basic project-level `.gitignore`. This should
|
18
|
+
primarily be used to avoid certain project-level files and directories from
|
19
|
+
being kept under source control. Different development-environments will
|
20
|
+
benefit from different collections of ignores.
|
21
|
+
|
22
|
+
OS-specific and editor-specific files should be ignored using a "global
|
23
|
+
ignore" that applies to all repositories on your system.
|
24
|
+
|
25
|
+
For example, add the following to your `~/.gitconfig`, where the `.gitignore`
|
26
|
+
in your HOME directory contains the files and directories you'd like to
|
27
|
+
globally ignore:
|
28
|
+
|
29
|
+
```gitignore
|
30
|
+
[core]
|
31
|
+
excludesfile = ~/.gitignore
|
32
|
+
```
|
33
|
+
|
34
|
+
* More on global ignores: https://help.github.com/articles/ignoring-files
|
35
|
+
* Comprehensive set of ignores on GitHub: https://github.com/github/gitignore
|
36
|
+
|
37
|
+
|
38
|
+
## .editorconfig
|
39
|
+
|
40
|
+
The `.editorconfig` file is provided in order to encourage and help you and
|
41
|
+
your team define and maintain consistent coding styles between different
|
42
|
+
editors and IDEs.
|
43
|
+
|
44
|
+
By default, `.editorconfig` includes some basic
|
45
|
+
[properties](http://editorconfig.org/#supported-properties) that reflect the
|
46
|
+
coding styles from the files provided by default, but you can easily change
|
47
|
+
them to better suit your needs.
|
48
|
+
|
49
|
+
In order for your editor/IDE to apply the
|
50
|
+
[properties](http://editorconfig.org/#supported-properties) from the
|
51
|
+
`.editorconfig` file, you will need to [install a
|
52
|
+
plugin]( http://editorconfig.org/#download).
|
53
|
+
|
54
|
+
__N.B.__ If you aren't using the server configurations provided by HTML5
|
55
|
+
Boilerplate, we highly encourage you to configure your server to block
|
56
|
+
access to `.editorconfig` files, as they can disclose sensitive information!
|
57
|
+
|
58
|
+
For more details, please refer to the [EditorConfig
|
59
|
+
project](http://editorconfig.org/).
|
60
|
+
|
61
|
+
|
62
|
+
## Server Configuration
|
63
|
+
|
64
|
+
H5BP includes a [`.htaccess`](#htaccess) file for the Apache HTTP server. If you are not using
|
65
|
+
Apache as your web server, then you are encouraged to download a
|
66
|
+
[server configuration](https://github.com/h5bp/server-configs) that corresponds
|
67
|
+
to your web server and environment.
|
68
|
+
|
69
|
+
A `.htaccess` (hypertext access) file is a
|
70
|
+
[Apache HTTP server configuration file](https://github.com/h5bp/server-configs-apache).
|
71
|
+
The `.htaccess` file is mostly used for:
|
72
|
+
|
73
|
+
* Rewriting URLs
|
74
|
+
* Controlling cache
|
75
|
+
* Authentication
|
76
|
+
* Server-side includes
|
77
|
+
* Redirects
|
78
|
+
* Gzipping
|
79
|
+
|
80
|
+
If you have access to the main server configuration file (usually called
|
81
|
+
`httpd.conf`), you should add the logic from the `.htaccess` file in, for
|
82
|
+
example, a <Directory> section in the main configuration file. This is usually
|
83
|
+
the recommended way, as using .htaccess files slows down Apache!
|
84
|
+
|
85
|
+
To enable Apache modules locally, please see:
|
86
|
+
https://github.com/h5bp/server-configs-apache/wiki/How-to-enable-Apache-modules.
|
87
|
+
|
88
|
+
In the repo the `.htaccess` is used for:
|
89
|
+
|
90
|
+
* Allowing cross-origin access to web fonts
|
91
|
+
* CORS header for images when browsers request it
|
92
|
+
* Enable `404.html` as 404 error document
|
93
|
+
* Making the website experience better for IE users better
|
94
|
+
* Media UTF-8 as character encoding for `text/html` and `text/plain`
|
95
|
+
* Enabling the rewrite URLs engine
|
96
|
+
* Forcing or removing the `www.` at the begin of a URL
|
97
|
+
* It blocks access to directories without a default document
|
98
|
+
* It blocks access to files that can expose sensitive information.
|
99
|
+
* It reduces MIME type security risks
|
100
|
+
* It forces compressing (gzipping)
|
101
|
+
* It tells the browser whether they should request a specific file from the
|
102
|
+
server or whether they should grab it from the browser's cache
|
103
|
+
|
104
|
+
When using `.htaccess` we recommend reading all inline comments (the rules after
|
105
|
+
a `#`) in the file once. There is a bunch of optional stuff in it.
|
106
|
+
|
107
|
+
If you want to know more about the `.htaccess` file check out
|
108
|
+
https://httpd.apache.org/docs/current/howto/htaccess.html.
|
109
|
+
|
110
|
+
Notice that the original repo for the `.htaccess` file is [this
|
111
|
+
one](https://github.com/h5bp/server-configs-apache).
|
112
|
+
|
113
|
+
|
114
|
+
## crossdomain.xml
|
115
|
+
|
116
|
+
The _cross-domain policy file_ is an XML document that gives a web client —
|
117
|
+
such as Adobe Flash Player, Adobe Reader, etc. — permission to handle data
|
118
|
+
across multiple domains, by:
|
119
|
+
|
120
|
+
* granting read access to data
|
121
|
+
* permitting the client to include custom headers in cross-domain requests
|
122
|
+
* granting permissions for socket-based connections
|
123
|
+
|
124
|
+
__e.g.__ If a client hosts content from a particular source domain and that
|
125
|
+
content makes requests directed towards a domain other than its own, the remote
|
126
|
+
domain would need to host a cross-domain policy file in order to grant access
|
127
|
+
to the source domain and allow the client to continue with the transaction.
|
128
|
+
|
129
|
+
For more in-depth information, please see Adobe's [cross-domain policy file
|
130
|
+
specification](https://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html).
|
131
|
+
|
132
|
+
|
133
|
+
## robots.txt
|
134
|
+
|
135
|
+
The `robots.txt` file is used to give instructions to web robots on what can
|
136
|
+
be crawled from the website.
|
137
|
+
|
138
|
+
By default, the file provided by this project includes the next two lines:
|
139
|
+
|
140
|
+
* `User-agent: *` - the following rules apply to all web robots
|
141
|
+
* `Disallow:` - everything on the website is allowed to be crawled
|
142
|
+
|
143
|
+
If you want to disallow certain pages you will need to specify the path in a
|
144
|
+
`Disallow` directive (e.g.: `Disallow: /path`) or, if you want to disallow
|
145
|
+
crawling of all content, use `Disallow: /`.
|
146
|
+
|
147
|
+
The `/robots.txt` file is not intended for access control, so don't try to
|
148
|
+
use it as such. Think of it as a "No Entry" sign, rather than a locked door.
|
149
|
+
URLs disallowed by the `robots.txt` file might still be indexed without being
|
150
|
+
crawled, and the content from within the `robots.txt` file can be viewed by
|
151
|
+
anyone, potentially disclosing the location of your private content! So, if
|
152
|
+
you want to block access to private content, use proper authentication instead.
|
153
|
+
|
154
|
+
For more information about `robots.txt`, please see:
|
155
|
+
|
156
|
+
* [robotstxt.org](http://www.robotstxt.org/)
|
157
|
+
* [How Google handles the `robots.txt` file](https://developers.google.com/webmasters/control-crawl-index/docs/robots_txt)
|
158
|
+
|
159
|
+
|
160
|
+
## browserconfig.xml
|
161
|
+
|
162
|
+
The `browserconfig.xml` file is used to customize the tile displayed when users
|
163
|
+
pin your site to the Windows 8.1 start screen. In there you can define custom
|
164
|
+
tile colors, custom images or even [live tiles](https://msdn.microsoft.com/en-us/library/ie/dn455106.aspx#CreatingLiveTiles).
|
165
|
+
|
166
|
+
By default, the file points to 2 placeholder tile images:
|
167
|
+
|
168
|
+
* `tile.png` (558x558px): used for `Small`, `Medium` and `Large` tiles.
|
169
|
+
This image resizes automatically when necessary.
|
170
|
+
* `tile-wide.png` (558x270px): user for `Wide` tiles.
|
171
|
+
|
172
|
+
Notice that IE11 uses the same images when adding a site to the `favorites`.
|
173
|
+
|
174
|
+
For more in-depth information about the `browserconfig.xml` file, please
|
175
|
+
see [MSDN](https://msdn.microsoft.com/en-us/library/ie/dn320426.aspx).
|
@@ -0,0 +1,130 @@
|
|
1
|
+
[HTML5 Boilerplate homepage](https://html5boilerplate.com) | [Documentation
|
2
|
+
table of contents](TOC.md)
|
3
|
+
|
4
|
+
# Usage
|
5
|
+
|
6
|
+
Once you have cloned or downloaded HTML5 Boilerplate, creating a site or app
|
7
|
+
usually involves the following:
|
8
|
+
|
9
|
+
1. Set up the basic structure of the site.
|
10
|
+
2. Add some content, style, and functionality.
|
11
|
+
3. Run your site locally to see how it looks.
|
12
|
+
4. (Optionally run a build script to automate the optimization of your site -
|
13
|
+
e.g. [ant build script](https://github.com/h5bp/ant-build-script))
|
14
|
+
5. Deploy your site.
|
15
|
+
|
16
|
+
|
17
|
+
## Basic structure
|
18
|
+
|
19
|
+
A basic HTML5 Boilerplate site initially looks something like this:
|
20
|
+
|
21
|
+
```
|
22
|
+
.
|
23
|
+
├── css
|
24
|
+
│ ├── main.css
|
25
|
+
│ └── normalize.css
|
26
|
+
├── doc
|
27
|
+
├── img
|
28
|
+
├── js
|
29
|
+
│ ├── main.js
|
30
|
+
│ ├── plugins.js
|
31
|
+
│ └── vendor
|
32
|
+
│ ├── jquery.min.js
|
33
|
+
│ └── modernizr.min.js
|
34
|
+
├── .editorconfig
|
35
|
+
├── .htaccess
|
36
|
+
├── 404.html
|
37
|
+
├── apple-touch-icon.png
|
38
|
+
├── browserconfig.xml
|
39
|
+
├── index.html
|
40
|
+
├── humans.txt
|
41
|
+
├── robots.txt
|
42
|
+
├── crossdomain.xml
|
43
|
+
├── favicon.ico
|
44
|
+
├── tile-wide.png
|
45
|
+
└── tile.png
|
46
|
+
```
|
47
|
+
|
48
|
+
What follows is a general overview of each major part and how to use them.
|
49
|
+
|
50
|
+
### css
|
51
|
+
|
52
|
+
This directory should contain all your project's CSS files. It includes some
|
53
|
+
initial CSS to help get you started from a solid foundation. [About the
|
54
|
+
CSS](css.md).
|
55
|
+
|
56
|
+
### doc
|
57
|
+
|
58
|
+
This directory contains all the HTML5 Boilerplate documentation. You can use it
|
59
|
+
as the location and basis for your own project's documentation.
|
60
|
+
|
61
|
+
### js
|
62
|
+
|
63
|
+
This directory should contain all your project's JS files. Libraries, plugins,
|
64
|
+
and custom code can all be included here. It includes some initial JS to help
|
65
|
+
get you started. [About the JavaScript](js.md).
|
66
|
+
|
67
|
+
### .htaccess
|
68
|
+
|
69
|
+
The default web server configs are for Apache. For more information, please
|
70
|
+
refer to the [Apache Server Configs
|
71
|
+
repository](https://github.com/h5bp/server-configs-apache).
|
72
|
+
|
73
|
+
Host your site on a server other than Apache? You're likely to find the
|
74
|
+
corresponding server configs project listed in our [Server Configs
|
75
|
+
](https://github.com/h5bp/server-configs/blob/master/README.md) repository.
|
76
|
+
|
77
|
+
### 404.html
|
78
|
+
|
79
|
+
A helpful custom 404 to get you started.
|
80
|
+
|
81
|
+
### browserconfig.xml
|
82
|
+
|
83
|
+
This file contains all settings regarding custom tiles for IE11.
|
84
|
+
|
85
|
+
For more info on this topic, please refer to
|
86
|
+
[MSDN](https://msdn.microsoft.com/en-us/library/ie/dn455106.aspx).
|
87
|
+
|
88
|
+
### .editorconfig
|
89
|
+
|
90
|
+
The `.editorconfig` file is provided in order to encourage and help you and
|
91
|
+
your team to maintain consistent coding styles between different
|
92
|
+
editors and IDEs. [Read more about the `.editorconfig` file](misc.md#editorconfig).
|
93
|
+
|
94
|
+
### index.html
|
95
|
+
|
96
|
+
This is the default HTML skeleton that should form the basis of all pages on
|
97
|
+
your site. If you are using a server-side templating framework, then you will
|
98
|
+
need to integrate this starting HTML with your setup.
|
99
|
+
|
100
|
+
Make sure that you update the URLs for the referenced CSS and JavaScript if you
|
101
|
+
modify the directory structure at all.
|
102
|
+
|
103
|
+
If you are using Google Universal Analytics, make sure that you edit the
|
104
|
+
corresponding snippet at the bottom to include your analytics ID.
|
105
|
+
|
106
|
+
### humans.txt
|
107
|
+
|
108
|
+
Edit this file to include the team that worked on your site/app, and the
|
109
|
+
technology powering it.
|
110
|
+
|
111
|
+
### robots.txt
|
112
|
+
|
113
|
+
Edit this file to include any pages you need hidden from search engines.
|
114
|
+
|
115
|
+
### crossdomain.xml
|
116
|
+
|
117
|
+
A template for working with cross-domain requests. [About
|
118
|
+
crossdomain.xml](misc.md#crossdomainxml).
|
119
|
+
|
120
|
+
### Icons
|
121
|
+
|
122
|
+
Replace the default `favicon.ico`, `tile.png`, `tile-wide.png` and Apple
|
123
|
+
Touch Icon with your own.
|
124
|
+
|
125
|
+
If you want to use different Apple Touch Icons for different resolutions please
|
126
|
+
refer to the [according documentation](extend.md#apple-touch-icons).
|
127
|
+
|
128
|
+
You might want to check out Hans' handy [HTML5 Boilerplate Favicon and Apple
|
129
|
+
Touch Icon
|
130
|
+
PSD-Template](https://drublic.de/blog/html5-boilerplate-favicons-psd-template/).
|
Binary file
|
File without changes
|
Binary file
|