Adding details to GitHub Pages deployment docs regarding relative URLs.

Fixes #1291.

site/docs/github-pages.md

@@ -54,6 +54,31 @@ actual software project for Jekyll, however the Jekyll website (that you’re
 looking at right now) is contained in the [gh-pages
 branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
 
+### Project Page URL Structure
+
+Sometimes it's nice to preview your Jekyll site before you push your `gh-pages`
+branch to GitHub. However, the subdirectory-like URL structure GitHub uses for
+Project Pages complicates the proper resolution of URLs. Here is an approach to
+utilizing the GitHub Project Page URL structure (`username.github.io/project-name/`)
+whilst maintaining the ability to preview your Jekyll site locally.
+
+1. In `_config.yml`, set the `baseurl` option to `/project-name` -- note the
+   leading slash and the **absence** of a trailing slash.
+2. When referencing JS or CSS files, do it like this:
+   `{% raw %}{{ site.baseurl}}/path/to/css.css{% endraw %}` -- note the slash
+   immediately following the variable (just before "path").
+3. When doing permalinks or internal links, do it like this:
+   `{% raw %}{{ site.baseurl }}{{ post.url }}{% endraw %}` -- note that there
+   is **no** slash between the two variables.
+4. Finally, if you'd like to preview your site before committing/deploying using
+   `jekyll serve`, be sure to pass an **empty string** to the `--baseurl` option,
+   so that you can view everything at `localhost:4000` normally (without
+   `/project-name` at the beginning): `jekyll serve --baseurl ''`
+
+This way you can preview your site locally from the site root on localhost,
+but when GitHub generates your pages from the gh-pages branch all the URLs
+will start with `/project-name` and resolve properly.
+
 <div class="note">
   <h5>GitHub Pages Documentation, Help, and Support</h5>
   <p>