From e63107ec8e1205d1e6cff177ff2fe190d002b1c2 Mon Sep 17 00:00:00 2001 From: Nicolas Gallagher Date: Tue, 31 Jul 2012 22:32:04 +0100 Subject: [PATCH] Rewrite documentation and add to repo Include all documentation related to the project and its code. This ensures that docs are available offline and that any future download will have docs that relevant for the version in use. This change involves a documentation rewrite to update, simplify, clarify, and consolidate it. --- doc/README.md | 38 ++++ doc/contribute.md | 102 +++++++++++ doc/crossdomain.md | 21 +++ doc/css.md | 134 ++++++++++++++ doc/extend.md | 435 +++++++++++++++++++++++++++++++++++++++++++++ doc/faq.md | 87 +++++++++ doc/htaccess.md | 321 +++++++++++++++++++++++++++++++++ doc/html.md | 169 ++++++++++++++++++ doc/js.md | 31 ++++ doc/misc.md | 25 +++ doc/usage.md | 108 +++++++++++ readme.md | 51 +++--- 12 files changed, 1501 insertions(+), 21 deletions(-) create mode 100644 doc/README.md create mode 100644 doc/contribute.md create mode 100644 doc/crossdomain.md create mode 100644 doc/css.md create mode 100644 doc/extend.md create mode 100644 doc/faq.md create mode 100644 doc/htaccess.md create mode 100644 doc/html.md create mode 100644 doc/js.md create mode 100644 doc/misc.md create mode 100644 doc/usage.md 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)