Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Rewrite documentation and add to repo #1154

Merged
merged 1 commit into from Aug 2, 2012

Conversation

Projects
None yet
5 participants
Owner

necolas commented Jul 31, 2012

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.

Owner

mathiasbynens commented Jul 31, 2012

Nice work!

@mathiasbynens mathiasbynens commented on an outdated diff Jul 31, 2012

doc/README.md
+* [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.
@mathiasbynens

mathiasbynens Jul 31, 2012

Owner

Can haz em dashes here?

@mathiasbynens mathiasbynens commented on an outdated diff Jul 31, 2012

doc/contribute.md
+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

@mathiasbynens mathiasbynens commented on an outdated diff Jul 31, 2012

doc/contribute.md
+> 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
@mathiasbynens

mathiasbynens Jul 31, 2012

Owner

And here too.

Owner

necolas commented Aug 1, 2012

24 hours for more feedback before I merge this in. Thanks.

Owner

paulirish commented Aug 1, 2012

Nice work sir!

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

+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 teh CDN version might not be available, and to facilitate offline

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

@@ -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 conditonal classes technique, applying classes to the `html`
@sindresorhus

sindresorhus Aug 1, 2012

Member

conditional

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+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.
+
+
+### Cachebusting
@sindresorhus

sindresorhus Aug 1, 2012

Member

Cache busting

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+whenever you update those resources.
+
+#### Example:
+
+```html
+<script src="/js/myscript.20120305.js"></script>
+<script src="/js/jqueryplugin.45.js"></script>
+<link rel="stylesheet" href="css/somestyle.49559939932.css">
+<link rel="stylesheet" href="css/anotherstyle.2.css">
+```
+
+**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 cachebusting involved adding a query string to the end of your
@sindresorhus

sindresorhus Aug 1, 2012

Member

cache busting

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

+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 [TwitterBootstrap](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 to I prevent phone numbers looking twice as large and having a Skype highlight?
+
+If this is occuring, it is because a user has the Skype browser extension

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

+[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 runing

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/extend.md
+
+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', 'scrool',

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/contribute.md
+
+Please read the following guidelines for reporting bugs:
+
+1. **Use the GitHub issue search** &mdash; 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** &mdash; the latest `master` or
+ development branch may already contain a fix.
+
+3. **Isolate the demonstrable problem** &mdash; 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** &mdash; provide a link to your reduced test case
+ when appropriate (e.g. if the issue is related to frond-end technologies).
Owner

necolas commented Aug 1, 2012

Thanks for catching a bunch of old and new typos!

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/extend.md
+* 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
+<link rel="sitemap" type="application/xml" title="Sitemap" href="/sitemap.xml">
+```
+
+### Hide pages from search engines
+
+According to Heather Champ, former community manager at flickr, you should not

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/extend.md
+
+
+## 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
+<meta http-equiv="imagetoolbar" content="false">
+```
+
+### Prompt users to switch to "Desktop Mode" in IE10 Metro
+
+IE10 does not support plugins, such as Flash, in Metro Mode. If your site
@sindresorhus

sindresorhus Aug 1, 2012

Member

Metro mode

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

+ 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 [TwitterBootstrap](http://twitter.github.com/bootstrap/) with HTML5 Boilerplate?
@sindresorhus

sindresorhus Aug 1, 2012

Member

Twitter Bootstrap

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+
+**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
@sindresorhus

sindresorhus Aug 1, 2012

Member

WampServer

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+
+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
+ affect.

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+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) are a mechanism that web servers and browsers use to

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

doc/htaccess.md
+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
@sindresorhus

sindresorhus Aug 1, 2012

Member

websites

more like this below

@sindresorhus sindresorhus commented on an outdated diff Aug 1, 2012

@@ -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, instead `main.js` you can make use of a JavaScript module
@sindresorhus

sindresorhus Aug 1, 2012

Member

instead of

Member

sindresorhus commented Aug 1, 2012

Really nice work on this @necolas 🎀
I especially like the contribution docs. Should be standard in every big project.

Owner

necolas commented Aug 1, 2012

Thanks again. Will fix these when I get home. The contribution section is a simplified version of my issue-guidelines repo.

@s10wen s10wen commented on an outdated diff Aug 2, 2012

+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 to I prevent phone numbers looking twice as large and having a Skype highlight?
@s10wen

s10wen Aug 2, 2012

Contributor

How *do I

@necolas necolas 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.
e63107e

@necolas necolas merged commit e63107e into master Aug 2, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment