diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000..d750974eac --- /dev/null +++ b/doc/README.md @@ -0,0 +1,38 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) + +# HTML5 Boilerplate documentation: + +## Getting started + +* [Usage](usage.md) — Overview of the project contents. +* [FAQ](faq.md) — Frequently asked questions, along with their answers. + +## The core of HTML5 Boilerplate + +* [HTML](html.md) — A guide to the default HTML. +* [CSS](css.md) — A guide to the default CSS. +* [JavaScript](js.md) — A guide to the default JavaScript. +* [.htaccess](htaccess.md) — All about the Apache web server config (also see + our [alternative server configs](https://github.com/h5bp/server-configs)). +* [crossdomain.xml](crossdomain.md) — An introduction to making use of + crossdomain requests. +* [Everything else](misc.md). + +## Development + +* [Contributing to HTML5 Boilerplate](contribute.md) — Guidelines on how to + contribute effectively. +* [Extending and customizing HTML5 Boilerplate](extend.md) — Going further with + the boilerplate. + +## Related projects + +HTML5 Boilerplate has several related projects to help improve the performance +of your site/app in various production environments. + +* [Server configs](https://github.com/h5bp/server-configs) — Configs for + non-Apache servers. +* [Node build script](https://github.com/h5bp/node-build-script) — A + feature-rich [grunt](https://github.com/cowboy/grunt) plugin. +* [Ant build script](https://github.com/h5bp/ant-build-script) — The original + HTML5 Boilerplate build script. diff --git a/doc/contribute.md b/doc/contribute.md new file mode 100644 index 0000000000..ed014236fc --- /dev/null +++ b/doc/contribute.md @@ -0,0 +1,102 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# Contributing to HTML5 Boilerplate + +♥ HTML5 Boilerplate and want to get involved? Thanks! There are plenty of ways +you can help! + + +## Reporting issues + +A bug is a _demonstrable problem_ that is caused by the code in the +repository. + +Please read the following guidelines for reporting bugs: + +1. **Use the GitHub issue search** — check if the issue has already been + reported. If it has been, please comment on the existing issue. + +2. **Check if the issue has been fixed** — the latest `master` or + development branch may already contain a fix. + +3. **Isolate the demonstrable problem** — make sure that the code in the + project's repository is _definitely_ responsible for the issue. Create a + [reduced test case](http://css-tricks.com/6263-reduced-test-cases/) - an + extremely simple and immediately viewable example of the issue. + +4. **Include a live example** — provide a link to your reduced test case + when appropriate (e.g. if the issue is related to (front-end technologies). + Please use [jsFiddle](http://jsfiddle.net) to host examples. + +Please try to be as detailed as possible in your report too. What is your +environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to assess and fix any potential bugs. + +### Example of a good bug report: + +> Short and descriptive title +> +> A summary of the issue and the browser/OS environment in which it occurs. If +> suitable, include the steps required to reproduce the bug. +> +> 1. This is the first step +> 2. This is the second step +> 3. Further steps, etc. +> +> `` (a link to the reduced test case) +> +> Any other information you want to share that is relevant to the issue being +> reported. This might include the lines of code that you have identified as +> causing the bug, and potential solutions (and your opinions on their +> merits). + +A good bug report shouldn't leave people needing to chase you up to get further +information that is required to assess or fix the bug. + + +## Pull requests + +Good pull requests — patches, improvements, new features — are a fantastic +help. They should remain focused in scope and avoid containing unrelated +commits. + +If your contribution involves a significant amount of work or substantial +changes to any part of the project, please open an issue to discuss it first. + +Please follow this process; it's the best way to get your work included in the +project: + +1. [Fork](http://help.github.com/fork-a-repo/) the project. + +2. Clone your fork (`git clone + https://github.com//html5-boilerplate.git`). + +3. Add an `upstream` remote (`git remote add upstream + https://github.com/h5bp/html5-boilerplate.git`). + +4. Get the latest changes from upstream (e.g. `git pull upstream + `). + +5. Create a new topic branch to contain your feature, change, or fix (`git + checkout -b `). + +6. Make sure that your changes adhere to the current coding conventions used + throughout the project - indentation, accurate comments, etc. Please update + any documentation that is relevant to the change you are making. + +7. Commit your changes in logical chunks; use git's [interactive + rebase](https://help.github.com/articles/interactive-rebase) feature to tidy + up your commits before making them public. Please adhere to these [git commit + message + guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) + or your pull request is unlikely be merged into the main project. + +8. Locally merge (or rebase) the upstream branch into your topic branch. + +9. Push your topic branch up to your fork (`git push origin + `). + +10. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a + clear title and description. Please mention which browsers you tested in. diff --git a/doc/crossdomain.md b/doc/crossdomain.md new file mode 100644 index 0000000000..e88acc3b71 --- /dev/null +++ b/doc/crossdomain.md @@ -0,0 +1,21 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# crossdomain.xml + +A cross-domain policy file is an XML document that grants a web client—such as +Adobe Flash Player, Adobe Reader, etc., permission to handle data across +multiple domains. When a client hosts content from a particular source domain +and that content makes requests directed towards a domain other than its own, +the remote domain would need to host a cross-domain policy file that grants +access to the source domain, allowing the client to continue with the +transaction. Policy files grant read access to data, permit a client to include +custom headers in cross-domain requests, and are also used with sockets to +grant permissions for socket-based connections. + +For full details, check out Adobe's article about the [cross-domain policy file +specification](http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html) + +Read the [Cross-domain policy file +specification](http://learn.adobe.com/wiki/download/attachments/64389123/CrossDomain_PolicyFile_Specification.pdf?version=1) +- (PDF, 129 KB) diff --git a/doc/css.md b/doc/css.md new file mode 100644 index 0000000000..b56e9ca3c0 --- /dev/null +++ b/doc/css.md @@ -0,0 +1,134 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# The CSS + +The HTML5 Boilerplate starting CSS includes: + +* [Normalize.css](https://github.com/necolas/normalize.css). +* Useful HTML5 Boilerplate defaults. +* Common helpers. +* Placeholder media queries. +* Print styles. + +This starting CSS does not rely on the presence of conditional classnames, +conditional style sheets, or Modernizr. It is ready to use whatever your +development preferences happen to be. + + +## Normalize.css + +Normalize.css is a modern, HTML5-ready alternative to CSS resets. It contains +extensive inline documentation. Please refer to the [Normalize.css +project](http://necolas.github.com/normalize.css/) for more information. + + +## HTML5 Boilerplate defaults + +This project includes a handful of base styles that build upon Normalize.css. +These include: + +* Basic typography setting to provide improved text readability by default. +* Protection against unwanted `text-shadow` during text highlighting. +* Tweaks to default image alignment, fieldsets, and textareas. +* A pretty Chrome Frame prompt. + +You are free to modify or add to these base styles as your project requires. + + +## Common helpers + +#### `.ir` + +Add the `.ir` class to any element you are applying image-replacement to. Be +sure to include `background-image: url(pathtoimage.png);` for that specific +element so that image replacement can occur. + +#### `.hidden` + +Add the `.hidden` class to any elements that you want to hide from all +presentations, including screen readers. It could be an element that will be +populated later with JavaScript or an element you will hide with JavaScript. Do +not use this for SEO keyword stuffing. That is just not cool. + +#### `.visuallyhidden` + +Add the `.visuallyhidden` class to hide text from browsers but make it +available for screen readers. You can use this to hide text that is specific to +screen readers but that other users should not see. [About invisible +content](http://www.webaim.org/techniques/css/invisiblecontent/), [Hiding +content for +accessibility](http://snook.ca/archives/html_and_css/hiding-content-for-accessibility), +[HTML5 Boilerplate +issue/research](https://github.com/h5bp/html5-boilerplate/issues/194/). + +#### `.invisible` + +Add the `.invisible` class to any element you want to hide without affecting +layout. When you use `display: none` an element is effectively removed from the +layout. But in some cases you want the element to simply be invisible while +remaining in the flow and not affecting the positioning of surrounding +content. + +#### `.clearfix` + +Adding `.clearfix` to an element will ensure that it always fully contains its +floated children. There have been many variants of the clearfix hack over the +years, and there are other hacks that can also help you to contain floated +children, but the HTML5 Boilerplate currently uses the [micro +clearfix](http://nicolasgallagher.com/micro-clearfix-hack/). + + +## Media Queries + +The boilerplate makes it easy to get started with a "Mobile First" and +[Responsive Web +Design](http://www.alistapart.com/articles/responsive-web-design/) approach to +development. But it's worth remembering that there are [no silver +bullets](http://www.cloudfour.com/css-media-query-for-mobile-is-fools-gold/). + +We include a placeholder Media Queries to build up your mobile styles for wider +viewports. It is recommended that you adapt these Media Queries based on the +content of your site rather than mirroring the fixed dimensions of specific +devices. + +If you do not want to take a "Mobile First" approach, you can simply edit or +remove these placeholder Media Queries. One possibility would be to work from +wide viewports down and use `max-width` MQs instead, e.g., `@media only screen +and (max-width: 480px)`. + +Take a look into the [Mobile +Boilerplate](https://github.com/h5bp/mobile-boilerplate) for additional features +that are useful when developing mobile websites. + + +## Print styles + +* Print styles are inlined to [reduce the number of page + requests](http://www.phpied.com/delay-loading-your-print-css/). +* We strip all background colors and change the font color to dark gray and + remove text-shadow. This is meant to help save printer ink. +* Anchors do not need colors to indicate they are linked. They are underlined + to indicate so. +* Anchors and Abbreviations are expanded to indicate where users reading the + printed page can refer to. +* But we do not want to show link text for image replaced elements (given that + they are primarily images). + +### Paged media styles + +* Paged media is supported only in a [few + browsers](http://en.wikipedia.org/wiki/Comparison_of_layout_engines_%28Cascading_Style_Sheets%29#Grammar_and_rules). +* Paged media support means browsers would know how to interpret instructions + on breaking content into pages and on orphans/widows. +* We use `page-break-inside: avoid;` to prevent an image and table row from + being split into two different pages, so use the same `page-break-inside: + avoid;` for that as well. +* Headings should always appear with the text they are titles for. So, we + ensure headings never appear in a different page than the text they describe + by using `page-break-after: avoid;`. +* We also apply a default margin for the page specified in `cm`. +* We do not want [orphans and + widows](http://en.wikipedia.org/wiki/Widows_and_orphans) to appear on pages + you print. So, by defining `orphans: 3` and `widows: 3` you define the minimal + number of words that every line should contain. diff --git a/doc/extend.md b/doc/extend.md new file mode 100644 index 0000000000..c8f8c6bb8b --- /dev/null +++ b/doc/extend.md @@ -0,0 +1,435 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.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. + + +## DNS prefetching + +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. + +### 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 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 +content. Less requests result in faster page load times. The perception of this +is increased on a mobile platform where DNS latency can be greater. + +#### Disable implicit prefetching + +```html + +``` + +Even with X-DNS-Prefetch-Control meta tag (or http header) browsers will still +prefetch any explicit dns-prefetch links. + +**_WARNING:_** THIS MAY MAKE YOUR SITE SLOWER IF YOU RELY ON RESOURCES FROM +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. + +```html + + +``` + +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/HTML/Element/meta#attr-charset) +element (which should go right at the top of the `head`), so the browser can +act on them ASAP. + +#### Common Prefetch Links + +Amazon S3: + +```html + +``` + +Google APIs: + +```html + +``` + +Microsoft Ajax Content Delivery Network: + +```html + + +``` + +### Browser support for DNS prefetching + +Chrome, Firefox 3.5+, Safari 5+, Opera (Unknown), IE 9 (called "Pre-resolution" +on blogs.msdn.com) + +### Further reading about DNS prefetching + +* https://developer.mozilla.org/En/Controlling_DNS_prefetching +* http://dev.chromium.org/developers/design-documents/dns-prefetching +* http://www.apple.com/safari/whats-new.html +* http://blogs.msdn.com/b/ie/archive/2011/03/17/internet-explorer-9-network-performance-improvements.aspx +* http://dayofjs.com/videos/22158462/web-browsers_alex-russel + + +## Search + +### Direct search spiders to your sitemap + +[Learn how to make a sitemap](http://www.sitemaps.org/protocol.php) + +```html + +``` + +### Hide pages from search engines + +According to Heather Champ, former community manager at Flickr, you should not +allow search engines to index your "Contact Us" or "Complaints" page if you +value your sanity. This is an HTML-centric way of achieving that. + +``` + +``` + +**_WARNING:_** DO NOT INCLUDE ON PAGES THAT SHOULD APPEAR IN SEARCH ENGINES. + +### Firefox and IE Search Plugins + +Sites with in-site search functionality should be strongly considered for a +browser search plugin. A "search plugin" is an XML file which defines how your +plugin behaves in the browser. [How to make a browser search +plugin](http://www.google.com/search?ie=UTF-8&q=how+to+make+browser+search+plugin). + +```html + +``` + + +## Internet Explorer + +### Suppress IE6 image toolbar + +Kill IE6's pop-up-on-mouseover toolbar for images that can interfere with +certain designs and be pretty distracting in general. + +```html + +``` + +### Prompt users to switch to "Desktop Mode" in IE10 Metro + +IE10 does not support plugins, such as Flash, in Metro mode. If your site +requires plugins, you can let users know that via the X-UA-Compatible meta +element, which will prompt them to switch to Desktop Mode. + +```html + +``` + +Here's what it looks like alongside H5BP's default X-UA-Compatible values: + +```html + +``` + +You can find more information in [Microsoft's IEBlog post about prompting for +plugin use in IE10 Metro +Mode](http://blogs.msdn.com/b/ie/archive/2012/01/31/web-sites-and-a-plug-in-free-web.aspx). + +### IE Pinned Sites (IE9+) + +Enabling your application for pinning will allow IE9 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 IE9 +Pinned Sites](http://msdn.microsoft.com/en-us/library/gg131029.aspx). + +### Name the Pinned Site for Windows + +Without this rule, Windows will use the page title as the name for your +application. + +```html + +``` + +### Give your Pinned Site a tooltip + +You know — a tooltip. A little textbox that appears when the user holds their +mouse over your Pinned Site's icon. + +```html + +``` + +### Set a default page for your Pinned Site + +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` + +```html + +``` + +### Recolor IE's controls manually for a Pinned Site + +IE9+ 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`). + +```html + +``` + +### 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. + +```html + +``` + +### Jump List "Tasks" for Pinned Sites + +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. + +```html + + +``` + + +## Facebook Open Graph data + +You can control the information that Facebook displays when users share your +site. Below are just the most basic data points you might need. For specific +content types (including "website"), see [Facebook's built-in Open Graph +content +templates](https://developers.facebook.com/docs/opengraph/objects/builtin/). +Take full advantage of Facebook's support for complex data and activity by +following the [Open Graph +tutorial](https://developers.facebook.com/docs/opengraph/tutorial/). + +```html + + + +``` + + +## URLs + +### Canonical URL + +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`. + +```html + +``` + +### Official shortlink + +Signal to the world "This is the shortened URL to use this page!" Poorly +supported at this time. Learn more by reading the [article about shortlinks on +the Microformats wiki](http://microformats.org/wiki/rel-shortlink). + +```html + +``` + + +## News Feeds + +### RSS + +Have an RSS feed? Link to it here. Want to [learn how to write an RSS feed from +scratch](http://www.rssboard.org/rss-specification)? + +```html + +``` + +### 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 +about](http://www.atomenabled.org/developers/syndication/). + +```html + +``` + +### Pingbacks + +Your server may be notified when another site links to yours. The href +attribute should contain the location of your pingback service. + +```html + +``` + +* High-level explanation: http://codex.wordpress.org/Introduction_to_Blogging#Pingbacks +* Step-by-step example case: http://www.hixie.ch/specs/pingback/pingback-1.0#TOC5 +* PHP pingback service: http://blog.perplexedlabs.com/2009/07/15/xmlrpc-pingbacks-using-php/ + + +## Google Analytics augments + +### More tracking settings + +The [optimized Google Analytics +snippet](http://mathiasbynens.be/notes/async-analytics-snippet) included with +HTML5 Boilerplate includes something like this: + +```js +var _gaq = [['_setAccount', 'UA-XXXXX-X'], ['_trackPageview']]; +``` + +In case you need more settings, just extend the array literal instead of +[`.push()`ing to the +array](http://mathiasbynens.be/notes/async-analytics-snippet#dont-push-it) +afterwards: + +```js +var _gaq = [['_setAccount', 'UA-XXXXX-X'], ['_trackPageview'], ['_setAllowAnchor', true]]; +``` + +### Anonymize IP addresses + +In some countries, no personal data may be transferred outside jurisdictions +that do not have similarly strict laws (i.e. from Germany to outside the EU). +Thus a webmaster using the Google Analytics script may have to ensure that no +personal (trackable) data is transferred to the US. You can do that with [the +`_gat.anonymizeIp` +option](http://code.google.com/apis/analytics/docs/gaJS/gaJSApi_gat.html#_gat._anonymizeIp). +In use it looks like this: + +```js +var _gaq = [['_setAccount', 'UA-XXXXX-X'], ['_gat._anonymizeIp'], ['_trackPageview']]; +``` + +### Track jQuery AJAX requests in Google Analytics + +An article by @JangoSteve explains how to [track jQuery AJAX requests in Google +Analytics](http://www.alfajango.com/blog/track-jquery-ajax-requests-in-google-analytics/). + +Add this to `plugins.js`: + +```js +/* + * Log all jQuery AJAX requests to Google Analytics + * See: http://www.alfajango.com/blog/track-jquery-ajax-requests-in-google-analytics/ + */ +if (typeof _gaq !== "undefined" && _gaq !== null) { + $(document).ajaxSend(function(event, xhr, settings){ + _gaq.push(['_trackPageview', settings.url]); + }); +} +``` + +### Track JavaScript errors in Google Analytics + +Add this function after `_gaq` is defined: + +```js +(function(window){ + var undefined, + link = function (href) { + var a = window.document.createElement('a'); + a.href = href; + return a; + }; + window.onerror = function (message, file, row) { + var host = link(file).hostname; + _gaq.push([ + '_trackEvent', + (host == window.location.hostname || host == undefined || host == '' ? '' : 'external ') + 'error', + message, file + ' LINE: ' + row, undefined, undefined, true + ]); + }; +}(window)); +``` + +### Track page scroll + +Add this function after `_gaq` is defined: + +```js +$(function(){ + var isDuplicateScrollEvent, + scrollTimeStart = new Date, + $window = $(window), + $document = $(document), + scrollPercent; + + $window.scroll(function() { + scrollPercent = Math.round(100 * ($window.height() + $window.scrollTop())/$document.height()); + if (scrollPercent > 90 && !isDuplicateScrollEvent) { //page scrolled to 90% + isDuplicateScrollEvent = 1; + _gaq.push(['_trackEvent', 'scroll', + 'Window: ' + $window.height() + 'px; Document: ' + $document.height() + 'px; Time: ' + Math.round((new Date - scrollTimeStart )/1000,1) + 's', + undefined, undefined, true + ]); + } + }); +}); +``` + + +## Miscellaneous + +* Use [HTML5 + 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 + results + [visibility](http://googlewebmastercentral.blogspot.com/2009/05/introducing-rich-snippets.html). + +* If you're building a web app you may want [native style momentum scrolling in + iOS5](http://johanbrook.com/browsers/native-momentum-scrolling-ios-5/) using + `-webkit-overflow-scrolling: touch`. + +* Avoid development/stage websites "leaking" into SERPs (search engine results + 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. + + +*Many thanks to [Brian Blakely](https://github.com/brianblakely) for +contributing much of this information.* diff --git a/doc/faq.md b/doc/faq.md new file mode 100644 index 0000000000..7da5f9ec07 --- /dev/null +++ b/doc/faq.md @@ -0,0 +1,87 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# Frequently asked questions + +## Why is the URL for jQuery without "http"? + +This is an intentional use of [protocol-relative +URLs](http://paulirish.com/2010/the-protocol-relative-url/) + +**N.B.** Using a protocol-relative URL for files that exist on a CDN is +problematic when you try to view your local files directly in the browser. The +browser will attempt to fetch the file from your local file system. We +recommend that you use a local server to test your pages (or Dropbox). This can +be done using Python by running `python -m SimpleHTTPServer` from your local +directory, using Ruby by installing and running +[asdf](https://rubygems.org/gems/asdf), and by installing any one of XAMPP, +MAMP, or WAMP. + + +### Why don't you automatically load the latest version of jQuery from the Google CDN? + +1. The latest version of jQuery may not be compatible with the existing + plugins/code on the site. Version updating should be an intentional + decision. +2. The latest version has a very short `max-age=3600` compares to the specific + version of `max-age=31536000`, which means you won't get the benefits of + long-term caching. + + +### Why is the Google Analytics code at the bottom? Google recommends it be placed the `head`. + +The advantage to placing it in the `head` is that you will track a user's +pageview even if they leave the page before it has been fully loaded. However, +putting the code at the bottom keeps all the scripts together and reinforces +that scripts at the bottom are the right move. + + +### How can I integrate [Twitter Bootstrap](http://twitter.github.com/bootstrap/) with HTML5 Boilerplate? + +You can use [Initializr](http://initializr.com) to create a custom build that +includes HTML5 Boilerplate with Twitter Bootstrap. + +Read more about how [HTML5 Boilerplate and Twitter Bootstrap complement each +other](http://www.quora.com/Is-Bootstrap-a-complement-OR-an-alternative-to-HTML5-Boilerplate-or-viceversa/answer/Nicolas-Gallagher). + + +### How do I prevent phone numbers looking twice as large and having a Skype highlight? + +If this is occurring, it is because a user has the Skype browser extension +installed. + +Use the following CSS to prevent Skype from formatting the numbers on your +page: + +``` +span.skype_pnh_container { + display: none !important; +} + +span.skype_pnh_print_container { + display: inline !important; +} +``` + + +### What is profiling, and how do I use it, why do I want it? + +[Firebug](http://michaelsync.net/2007/09/10/firebug-tutorial-logging-profiling-and-commandline-part-ii) +and [Chrome Dev +tools](http://code.google.com/chrome/devtools/docs/profiles.html) offer +profiling, but there is no easy way to profile IE6 and IE7. If you're focused +on providing the most responsive experience possible (you should be!) then +profiling should be part of your development workflow. + + +### Do I need to upgrade my sites each time a new version of HTML5 Boilerplate is released? + +No. You don't normally replace the foundations of a house once it has been +built. 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 for support questions? + +Please ask for help on +[StackOverflow](http://stackoverflow.com/questions/tagged/html5boilerplate). diff --git a/doc/htaccess.md b/doc/htaccess.md new file mode 100644 index 0000000000..5d325db53c --- /dev/null +++ b/doc/htaccess.md @@ -0,0 +1,321 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# .htaccess + +In Apache HTTP server, `.htaccess` (hypertext access) is the configuration file +that allows for web server configuration. HTML5 Boilerplate includes a number +of best practice server rules for making web pages fast and secure, these rules +can be applied by configuring `.htaccess` file. + +**You'll want to have these modules enabled for optimum performance:** + +* `mod_setenvif.c` (setenvif_module) +* `mod_headers.c` (headers_module) +* `mod_deflate.c` (deflate_module) +* `mod_filter.c` (filter_module) +* `mod_expires.c` (expires_module) +* `mod_rewrite.c` (rewrite_module) + + +## On Windows + +You've got a couple of options that depend on how you installed Apache. + +1. **WampServer**. This is by far the simplest option. If you have installed + WampServer just click on the icon in the task bar, hover over the Apache + section in the menu that comes up and then hover over the modules section. + You will be presented with a list of modules. Simply click on a module name + to enable it (or disable it if it is already enabled). A check mark next to + a module indicates that it is enabled. WampServer will automatically restart + the Apache service after you enable a module. +2. **Manually editing `httpd.conf`**. This assumes that you have manually + installed Apache. You will need to locate the `httpd.conf` file which is + normally in the `conf` folder in the folder where you installed Apache (for + example `C:\apache\conf\httpd.conf`). Open up this file in a text editor. Near + the top (after a bunch of comments) you will see a long list of modules. Check + to make sure that the modules listed above are not commented out. If they + are, go ahead and uncomment them and restart Apache. + +That's it, you're done! + + +## On Linux + +These instructions should work on any distribution where `apt-get` has been +used to install Apache. + +1. Open up a terminal and type the following command. Enter your password when + prompted. + + `sudo a2enmod setenvif headers deflate filter expires rewrite include` + +1. Restart apache by using the following command so the new configuration takes + effect. + + `sudo /etc/init.d/apache2 restart` + +That's it, you're done! + + +## On Mac + +Coming soon... + + +## Security + +Do not turn off your ServerSignature (i.e., the `Server:` HTTP header). Serious +attackers can use other kinds of fingerprinting methods to figure out the +actual server and components running behind a port. Instead, as a site owner, +you should keep track of what's listening on ports on hosts that you control. +Run a periodic scanner to make sure nothing suspicious is running on a host you +control, and use the ServerSignature to determine if this is the web server and +version that you expect. + +## Performance + +### Configure ETags + +```apache +FileETag None +``` + +Entity tags (ETags) is a mechanism that web servers and browsers use to +determine whether the component in the browser's cache matches the one on the +origin server. (An "entity" is another word a "component": images, scripts, +stylesheets, etc.) ETags were added to provide a mechanism for validating +entities that is more flexible than the last-modified date. An `ETag` is a +string that uniquely identifies a specific version of a component. The only +format constraints are that the string be quoted. The origin server specifies +the component's `ETag` using the `ETag` response header. + +```http +HTTP/1.1 200 OK +Last-Modified: Tue, 12 Dec 2006 03:03:59 GMT +ETag: "10c24bc-4ab-457e1c1f" +Content-Length: 12195 +``` + +Later, if the browser has to validate a component, it uses the `If-None-Match` +header to pass the `ETag` back to the origin server. If the ETags match, a 304 +status code is returned reducing the response by 12195 bytes for this +example. + +```http +GET /i/yahoo.gif HTTP/1.1 +Host: us.yimg.com +If-Modified-Since: Tue, 12 Dec 2006 03:03:59 GMT +If-None-Match: "10c24bc-4ab-457e1c1f" +HTTP/1.1 304 Not Modified +``` + +The problem with ETags is that they typically are constructed using attributes +that make them unique to a specific server hosting a site. ETags won't match +when a browser gets the original component from one server and later tries to +validate that component on a different server, a situation that is all too +common on web sites that use a cluster of servers to handle requests. By +default, both Apache and IIS embed data in the ETag that dramatically reduces +the odds of the validity test succeeding on web sites with multiple servers. + +The ETag format for Apache 1.3 and 2.x is inode-size-timestamp. Although a +given file may reside in the same directory across multiple servers, and have +the same file size, permissions, timestamp, etc., its inode is different from +one server to the next. + +IIS 5.0 and 6.0 have a similar issue with ETags. The format for ETags on IIS is +Filetimestamp:ChangeNumber. A ChangeNumber is a counter used to track +configuration changes to IIS. It's unlikely that the ChangeNumber is the same +across all IIS servers behind a web site. + +The end result is ETags generated by Apache and IIS for the exact same +component won't match from one server to another. If the ETags don't match, the +user doesn't receive the small, fast 304 response that ETags were designed for; +instead, they'll get a normal 200 response along with all the data for the +component. If you host your web site on just one server, this isn't a problem. +But if you have multiple servers hosting your web site, and you're using Apache +or IIS with the default ETag configuration, your users are getting slower +pages, your servers have a higher load, you're consuming greater bandwidth, and +proxies aren't caching your content efficiently. Even if your components have a +far future Expires header, a conditional GET request is still made whenever the +user hits Reload or Refresh. + +If you're not taking advantage of the flexible validation model that ETags +provide, it's better to just remove the ETag altogether. The Last-Modified +header validates based on the component's timestamp. And removing the ETag +reduces the size of the HTTP headers in both the response and subsequent +requests. This Microsoft Support article describes how to remove ETags. In +Apache, this is done by simply adding the above line to your Apache +configuration file. + + +### Gzip Components + +Compression reduces response times by reducing the size of the HTTP response. + +Starting with HTTP/1.1, web clients indicate support for compression with the +Accept-Encoding header in the HTTP request. + +``` +Accept-Encoding: gzip, deflate +``` + +If the web server sees this header in the request, it may compress the response +using one of the methods listed by the client. The web server notifies the web +client of this via the Content-Encoding header in the response. + +``` +Content-Encoding: gzip +``` + +Gzip is the most popular and effective compression method at this time. It was +developed by the GNU project and standardized by RFC 1952. The only other +compression format you're likely to see is deflate, but it's less effective and +less popular. + +Gzipping generally reduces the response size by about 70%. Approximately 90% of +today's Internet traffic travels through browsers that claim to support gzip. +If you use Apache, the module configuring gzip depends on your version: Apache +1.3 uses `mod_gzip` while Apache 2.x uses `mod_deflate`. + +There are known issues with browsers and proxies that may cause a mismatch in +what the browser expects and what it receives with regard to compressed +content. Fortunately, these edge cases are dwindling as the use of older +browsers drops off. The Apache modules help out by adding appropriate Vary +response headers automatically. + +Servers choose what to gzip based on file type, but are typically too limited +in what they decide to compress. Most web sites gzip their HTML documents. It's +also worthwhile to gzip your scripts and stylesheets, but many web sites miss +this opportunity. In fact, it's worthwhile to compress any text response +including XML and JSON. Image and PDF files should not be gzipped because they +are already compressed. Trying to gzip them not only wastes CPU but can +potentially increase file sizes. + +Gzipping as many appropriate file types as possible is an easy way to reduce +page weight and accelerate the user experience. + + +### Cache busting + +A first-time visitor to your page may have to make several HTTP requests, but +by using the Expires header you make those components cacheable. This avoids +unnecessary HTTP requests on subsequent page views. Expires headers are most +often used with images, but they should be used on all components including +scripts, stylesheets, etc. + +Traditionally, if you use a far future Expires header you have to change the +component's filename whenever the component changes. + +The H5BP `.htaccess` has built-in filename cache busting. To use it, uncomment +the relevant lines in the `.htaccess` file. + +Doing so will route all requests for `/path/filename.20120101.ext` to +`/path/filename.ext`. To use this, just add a time-stamp number (or your own +numbered versioning system) into your resource filenames in your HTML source +whenever you update those resources. + +#### Example: + +```html + + + + +``` + +**N.B. You do not have to rename the resource on the filesystem.** All you have +to do is add the timestamp number to the filename in your HTML source. The +`.htaccess` directive will serve up the proper file. + +Traditional cache busting involved adding a query string to the end of your +JavaScript or CSS filename whenever you updated it. + +```html + +``` + +However, as [Steve Souders](http://stevesouders.com/) explains in [*Revving +Filenames: don’t use +querystring*](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/), +the query string approach is not always reliable for clients behind a Squid +Proxy Server. + + +## Trailing slash redirects + +Trailing slash redirects can be done by adding one of the options below in `.htaccess`. + +### Option 1 +Rewrite `domain.com/foo` -> `domain.com/foo/`. + +```apache +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$ +RewriteRule ^(.*)$ $1/ [R=301,L] +``` + +### Option 2 +Rewrite `domain.com/foo/` -> `domain.com/foo` + +```apache +RewriteRule ^(.*)/$ $1 [R=301,L] +``` + +Here are some tips to show you how to integrate the rewrite rules with +different CMS tools. There are four areas you need to look out for: + +### 1. Keep a backup + +If you use trailing slash redirects on an existing site, always keep a backup +of your `.htaccess` and test thoroughly on your staging server before using it on +a production server. + +### 2. Don't replace existing rules, merge + +For example, if you use CodeIgniter you may have existing URL rewrite rules like: + +```apache +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule ^(.*)$ index.php/$1 +``` + +Merge the above with H5BP rules below: + +```apache +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$ +RewriteRule ^(.*)$ $1/ [R=301,L] +``` + +### 3. Be careful of the order + +Make sure you test thoroughly in your staging environment. For the above +example, the order is add trailing slash first, and add your existing rule +after: + +```apache +# this adds trailing slash +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_URI} !(\.[a-zA-Z0-9]{1,5}|/|#(.*))$ +RewriteRule ^(.*)$ $1/ [R=301,L] + +# this gets rid of index.php +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d +RewriteRule ^(.*)$ index.php/$1 +``` + +### 4. Double-check `RewriteBase` path is correct + +Make sure your `RewriteBase` path points to the correct location and sits above +any rewrite rules. This usually happens to those have WordPress and ran the +auto install. For instance, if you have a site at `example.com/blog`, your +RewriteBase may look like: + +```apache +RewriteBase /blog/ +``` + +If you already have a working RewriteBase, keep that and don't remove it. diff --git a/doc/html.md b/doc/html.md new file mode 100644 index 0000000000..4d73ca59a8 --- /dev/null +++ b/doc/html.md @@ -0,0 +1,169 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# The HTML + +## Conditional `html` classes + +A series of IE conditional comments apply the relevant IE-specific classes to +the `html` tag. This provides one method of specifying CSS fixes for specific +legacy versions of IE. While you may or may not choose to use this technique in +your project code, HTML5 Boilerplate's default CSS does not rely on it. + +When using the conditional classes technique, applying classes to the `html` +element has several benefits: + +* It avoids a [file blocking + issue](http://webforscher.wordpress.com/2010/05/20/ie-6-slowing-down-ie-8/) + discovered by Stoyan Stefanov and Markus Leptien. +* It avoids the need for an empty comment that also fixes the above issue. +* CMSes like WordPress and Drupal use the body class more heavily. This makes + integrating there a touch simpler. +* It still validates as HTML5. +* It uses the same element as Modernizr (and Dojo). That feels nice. +* It can improve the clarity of code in multi-developer teams. + + +## The `no-js` class + +Allows you to more easily explicitly add custom styles when JavaScript is +disabled (`no-js`) or enabled (`js`). More here: [Avoiding the +FOUC](http://paulirish.com/2009/avoiding-the-fouc-v3/). + + +## The order of meta tags, and `` + +As recommended by [the HTML5 +spec](http://www.whatwg.org/specs/web-apps/current-work/complete/semantics.html#charset) +(4.2.5.5 Specifying the document's character encoding), add your charset +declaration early (before any ASCII art ;) to avoid a potential +[encoding-related security +issue](http://code.google.com/p/doctype/wiki/ArticleUtf7) in IE. It should come +in the first [1024 +bytes](http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#charset). + +The charset should also come before the `<title>` tag, due to [potential XSS +vectors](http://code.google.com/p/doctype-mirror/wiki/ArticleUtf7). + +The meta tag for compatibility mode [needs to be before all elements except +title and meta](http://h5bp.com/f "Defining Document Compatibility - MSDN"). +And that same meta tag can only be invoked for Google Chrome Frame if it is +within the [first 1024 +bytes](http://code.google.com/p/chromium/issues/detail?id=23003). + + +## X-UA-Compatible + +This makes sure the latest version of IE is used in versions of IE that contain +multiple rendering engines. Even if a site visitor is using IE8 or IE9, it's +possible that they're not using the latest rendering engine their browser +contains. To fix this, use: + +```html +<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> +``` + +The `meta` tag tells the IE rendering engine two things: + +1. It should use the latest, or edge, version of the IE rendering environment +2. If already installed, it should use the Google Chrome Frame rendering + engine. + +This `meta` tag ensures that anyone browsing your site in IE is treated to the +best possible user experience that their browser can offer. + +This line breaks validation, and the Google Chrome Frame part won't work inside +a conditional comment. To avoid these edge case issues it is recommended that +you **remove this line and use the `.htaccess`** (or other server config) +to send these headers instead. You also might want to read [Validating: +X-UA-Compatible](http://groups.google.com/group/html5boilerplate/browse_thread/thread/6d1b6b152aca8ed2). + +If you are serving your site on a non-standard port, you will need to set this +header on the server-side. This is because the IE preference option 'Display +intranet sites in Compatibility View' is checked by default. + + +## 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 +Apple developer docs](http://j.mp/mobileviewport). HTML5 Boilerplate comes with +a simple setup that strikes a good balance for general use cases. + +```html +<meta name="viewport" content="width=device-width"> +``` + +## Favicons and Touch Icons + +The shortcut icons should be put in the root directory of your site. HTML5 +Boilerplate comes with a default set of icons (include favicon and Apple Touch +Icons) that you can use as a baseline to create your own. + +If your site is in a sub-directory, make sure you include `link` tags in the +HTML source so that the icons can render. + +For a comprehensive overview, please read [Everything you always wanted to know +about touch icons](http://mathiasbynens.be/notes/touch-icons) by Mathias +Bynens. + +## Modernizr + +HTML5 Boilerplate uses a custom build of Modernizr. + +[Modernizr](http://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. + +In general, in order to keep page load times to a minimum, it's best to call +any JavaScript at the end of the page because if a script is slow to load +from an external server it may cause the whole page to hang. That said, the +Modernizr script *needs* to run *before* the browser begins rendering the page, +so that browsers lacking support for some of the new HTML5 elements are able to +handle them properly. Therefore the Modernizr script is the only JavaScript +file synchronously loaded at the top of the document. + + +## 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. + +### Google Chrome Frame + +The main content area of the boilerplate includes a prompt to install Chrome +Frame (which no longer requires administrative rights) for users of IE 6. If +you intended to support IE 6, then you should remove the snippet of code. + +### Google CDN for jQuery + +The Google CDN version of the jQuery JavaScript library is referenced towards +the bottom of the page using a protocol-independent path (read more about this +in the [FAQ](faq.md). A local fallback of jQuery is included for rare instances +when the CDN version might not be available, and to facilitate offline +development. + +Regardless of which JavaScript library you choose to use, it is well worth the +time and effort to look up and reference the Google CDN (Content Delivery +Network) version. Your users may already have this version cached in their +browsers, and Google's CDN is likely to deliver the asset faster than your +server. + +### Google Analytics Tracking Code + +Finally, an optimized version of the latest Google Analytics tracking code is +included. 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: + +* [Optimizing the asynchronous Google Analytics + snippet](http://mathiasbynens.be/notes/async-analytics-snippet). +* [Tracking Site Activity - Google + Analytics](http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html). diff --git a/doc/js.md b/doc/js.md new file mode 100644 index 0000000000..5a52621c31 --- /dev/null +++ b/doc/js.md @@ -0,0 +1,31 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# The JavaScript + +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. +For larger projects, you can make use of a JavaScript module loader, like +[Require.js](http://requirejs.org/), to load any other scripts you need to +run. + +## plugins.js + +This file can be used to contain all your plugins, such as jQuery plugins and +other 3rd party scripts. + +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](http://docs.jquery.com/Plugins/Authoring#Getting_Started) + +## vendor + +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](http://www.modernizr.com/download/). diff --git a/doc/misc.md b/doc/misc.md new file mode 100644 index 0000000000..1f7ba2199c --- /dev/null +++ b/doc/misc.md @@ -0,0 +1,25 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation table of contents](README.md) + +# Miscellaneous + +## .gitignore + +HTML5 Boilerplate includes a basic project-level `.gitignore`. This should +primarily be used to avoid certain project-level files and directories from +being kept under source control. Different development-environments will +benefit from different collections of ignores. + +OS-specific and editor-specific files should be ignored using a "global +ignore" that applies to all repositories on your system. + +For example, add the following to your `~/.gitconfig`, where the `.gitignore` +in your HOME directory contains the files and directories you'd like to +globally ignore: + +```gitignore +[core] + excludesfile = ~/.gitignore +``` + +* More on global ignores: http://help.github.com/ignore-files/ +* Comprehensive set of ignores on GitHub: https://github.com/github/gitignore diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 0000000000..d0b28d2a40 --- /dev/null +++ b/doc/usage.md @@ -0,0 +1,108 @@ +[HTML5 Boilerplate homepage](http://html5boilerplate.com) | [Documentation +table of contents](README.md) + +# Usage + +Once you have cloned or downloaded HTML5 Boilerplate, creating a site or app +usually involves the following: + +1. Set up the basic structure of the site. +2. Add some content, style, and functionality. +3. Run your site locally to see how it looks. +4. (Optionally run a build script to automate the optimization of your site - + e.g. [ant build script](https://github.com/h5bp/ant-build-script) or [node + build script](https://github.com/h5bp/node-build-script)). +5. Deploy your site. + + +## Basic structure + +A basic HTML5 Boilerplate site initially looks something like this: + +``` +. +├── css +│ └── main.css +├── doc +├── img +├── js +│ ├── main.js +│ ├── plugins.js +│ └── vendor +│ ├── jquery-1.7.2.min.js +│ └── modernizr-2.6.1.min.js +├── .htaccess +├── 404.html +├── index.html +├── humans.txt +├── robots.txt +├── crossdomain.xml +├── favicon.ico +└── [apple-touch-icons] +``` + +What follows is a general overview of each major part and how to use them. + +### css + +This directory should contain all your project's CSS files. It includes some +initial CSS to help get you started from a solid foundation. [About the +CSS](css.md). + +### doc + +This directory contains all the HTML5 Boilerplate documentation. You can use it +as the location and basis for your own project's documentation. + +### js + +This directory should contain all your project's JS files. Libraries, plugins, +and custom code can all be included here. It includes some initial JS to help +get you started. [About the JavaScript](js.md). + +### .htaccess + +The default web server config is for Apache. [About the .htaccess](htaccess.md). + +Host your site on a server other than Apache? You're likely to find the +corresponding configuration file in our [server configs +repo](https://github.com/h5bp/server-configs). If you cannot find a +configuration file for your setup, please consider contributing one so that +others can benefit too. + +### 404.html + +A helpful custom 404 to get you started. + +### index.html + +This is the default HTML skeleton that should form the basis of all pages on +your site. If you are using a server-side templating framework, then you will +need to integrate this starting HTML with your setup. + +Make sure that you update the URLs for the referenced CSS and JavaScript if you +modify the directory structure at all. + +If you are using Google Analytics, make sure that you edit the corresponding +snippet at the bottom to include your analytics ID. + +### humans.txt + +Edit this file to include the team that worked on your site/app, and the +technology powering it. + +### robots.txt + +Edit this file to include any pages you need hidden from search engines. + +### crossdomain.xml + +A template for working with cross-domain requests. [About +crossdomain.xml](crossdomain.md). + +### icons + +Replace the default `favicon.ico` and apple touch icons with your own. You +might want to check out Hans Christian's handy [HTML5 Boilerplate Favicon and +Apple Touch Icon +PSD-Template](http://drublic.de/blog/html5-boilerplate-favicons-psd-template/). diff --git a/readme.md b/readme.md index 681e7e507e..ceabb77a5d 100644 --- a/readme.md +++ b/readme.md @@ -1,13 +1,27 @@ # [HTML5 Boilerplate](http://html5boilerplate.com) -HTML5 Boilerplate is a professional front-end template that helps you build fast, robust, adaptable, and future-proof websites. Spend more time developing and less time reinventing the wheel. +HTML5 Boilerplate is a professional front-end template that helps you build +fast, robust, adaptable, and future-proof websites. Spend more time developing +and less time reinventing the wheel. -This project is the product of many years of iterative development and combined community knowledge. It does not impose a specific development philosophy or framework, so you're free to architect your code in the way that you want. +This project is the product of many years of iterative development and combined +community knowledge. It does not impose a specific development philosophy or +framework, so you're free to architect your code in the way that you want. + +* Source: [http://github.com/h5bp/html5-boilerplate](http://github.com/h5bp/html5-boilerplate) +* Homepage: [http://html5boilerplate.com](http://html5boilerplate.com) +* Twitter: [@h5bp](http://twitter.com/h5bp) ## Quick start -Clone the git repo - `git clone git://github.com/h5bp/html5-boilerplate.git` - or [download it](https://github.com/h5bp/html5-boilerplate/zipball/master) +Choose of the following options: + +1. Download the latest stable release from + [html5boilerplate.com](http://html5boilerplate.com/) or a custom build from + [Initializr](http://www.initializr.com). +2. Clone the git repo — `git clone + https://github.com/h5bp/html5-boilerplate.git` ## Features @@ -19,37 +33,32 @@ Clone the git repo - `git clone git://github.com/h5bp/html5-boilerplate.git` - o * IE-specific classes for easier cross-browser control. * A default print stylesheet, performance optimized. * Mobile browser optimizations. -* Protection against any stray `console.log` causing JavaScript errors in IE6/7. +* Protection against any stray `console.log` causing JavaScript errors in + IE6/7. * The latest jQuery via CDN, with a local fallback. -* A custom Modernizr build for feature detection. +* The latest Modernizr build for feature detection. * An optimized Google Analytics snippet. -* Apache server caching, compression, and other configuration defaults for Grade-A performance. +* Apache server caching, compression, and other configuration defaults for + Grade-A performance. * Cross-domain Ajax and Flash. * "Delete-key friendly." Easy to strip out parts you don't need. * Extensive inline and accompanying documentation. -## Contributing +## Documentation -Anyone and everyone is welcome to [contribute](https://github.com/h5bp/html5-boilerplate/wiki/contribute). Hundreds of developers have helped make the HTML5 Boilerplate what it is today. +Take a look at the [documentation table of contents](doc/README.md). This +documentation is bundled with the project, which makes it readily available for +offline reading and provides a useful starting point for any documentation you +want to write about your project. -## Project information +## Contributing -* Source: http://github.com/h5bp/html5-boilerplate -* Web: http://html5boilerplate.com -* Docs: http://html5boilerplate.com/docs -* Twitter: http://twitter.com/h5bp +Anyone and everyone is welcome to [contribute](doc/contribute.md). Hundreds of +developers have helped make the HTML5 Boilerplate what it is today. ## License -### Major components: - -* jQuery: MIT/GPL license -* Modernizr: MIT/BSD license -* Normalize.css: Public Domain - -### Everything else: - The Unlicense (aka: public domain)