Rewrite documentation and add to repo

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.

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.
+>
+> `<url>` (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/<your-username>/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
+   <dev-branch>`).
+
+5. Create a new topic branch to contain your feature, change, or fix (`git
+   checkout -b <topic-branch-name>`).
+
+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
+   <topic-branch-name>`).
+
+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.

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)

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.