Docs: GitHub Pages instructions (#6384)

Merge pull request 6384

docs/_docs/github-pages.md

@@ -4,103 +4,82 @@ permalink: /docs/github-pages/
 ---
 
 [GitHub Pages](https://pages.github.com) are public web pages for users,
-organizations, and repositories, that are freely hosted on GitHub's
+organizations, and repositories, that are freely hosted on GitHub's `github.io`
-`github.io` domain or on a custom domain name of your choice. GitHub Pages are
+domain or on a custom domain name of your choice. GitHub Pages are powered by
-powered by Jekyll behind the scenes, so in addition to supporting regular HTML
+Jekyll behind the scenes, so they're a great way to host your Jekyll-powered
-content, they’re also a great way to host your Jekyll-powered website for free.
+website for free.
+
+Your site is automatically generated by GitHub Pages when you push your source
+files. Note that GitHub Pages works equally well for regular HTML content,
+simply because Jekyll treats files without YAML front matter as static assets.
+So if you only need to push generated HTML, you're good to go without any
+further setup.
 
 Never built a website with GitHub Pages before? [See this marvelous guide by
-Jonathan McGlone to get you up and running](http://jmcglone.com/guides/github-pages/).
+Jonathan McGlone](http://jmcglone.com/guides/github-pages/) to get you up and
-This guide will teach you what you need to know about Git, GitHub, and Jekyll to create your very own website on GitHub Pages.
+running. This guide will teach you what you need to know about Git, GitHub, and
+Jekyll to create your very own website on GitHub Pages.
+
+##  The github-pages gem
+
+Our friends at GitHub have provided the
+[github-pages](https://github.com/github/pages-gem) gem which is used to manage
+[Jekyll and its dependencies on GitHub Pages](https://pages.github.com/versions/).
+Using it in your projects means that when you deploy your site to GitHub Pages,
+you will not be caught by unexpected differences between various versions of the
+gems.
+
+Note that GitHub Pages runs in `safe` mode and only allows [a set of whitelisted
+plugins](https://help.github.com/articles/configuring-jekyll-plugins/#default-plugins).
+
+To use the currently-deployed version of the gem in your project, add the
+following to your `Gemfile`:
+
+```ruby
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
+```
+
+Be sure to run `bundle update` often.
+
+<div class="note">
+  <h5>GitHub Pages Documentation, Help, and Support</h5>
+  <p>
+    For more information about what you can do with GitHub Pages, as well as for
+    troubleshooting guides, you should check out
+    <a href="https://help.github.com/categories/github-pages-basics/">GitHub’s Pages Help section</a>.
+    If all else fails, you should contact <a href="https://github.com/contact">GitHub Support</a>.
+  </p>
+</div>
 
 ### 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. In order to assure your site builds properly, use `site.github.url` in your URLs.
+Project Pages complicates the proper resolution of URLs. In order to assure your
+site builds properly, use the handy [URL filters](../templates/#filters):
 
 ```html
 {% raw %}
-<!-- Useful for styles with static names... -->
+<!-- For styles with static names... -->
-<link href="{{ site.github.url }}/path/to/css.css" rel="stylesheet">
+<link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
-<!-- and for documents/pages whose URLs can change... -->
+<!-- For documents/pages whose URLs can change... -->
-[{{ page.title }}]("{{ page.url | prepend: site.github.url }}")
+[{{ page.title }}]("{{ page.url | relative_url }}")
 {% endraw %}
 ```
 
 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
+but when GitHub generates your pages from the `gh-pages` branch all the URLs
 will resolve properly.
 
 ## Deploying Jekyll to GitHub Pages
 
 GitHub Pages work by looking at certain branches of repositories on GitHub.
-There are two basic types available: user/organization pages and project pages.
+There are two basic types available: [user/organization and project pages](https://help.github.com/articles/user-organization-and-project-pages/).
 The way to deploy these two types of sites are nearly identical, except for a
 few minor details.
 
-<div class="note protip" markdown="1">
-<div markdown="1">
-</div>
-
-##### Use the `github-pages` gem
-
-Our friends at GitHub have provided the
-[github-pages](https://github.com/github/pages-gem)
-gem which is used to manage Jekyll and its dependencies on
-GitHub Pages. Using it in your projects means that when you deploy
-your site to GitHub Pages, you will not be caught by unexpected
-differences between various versions of the gems. To use the
-currently-deployed version of the gem in your project, add the
-following to your `Gemfile`:
-
-<div class="code-block" markdown="1">
-<div markdown="1">
-</div>
-
-```ruby
-source 'https://rubygems.org'
-
-require 'json'
-require 'open-uri'
-versions = JSON.parse(open('https://pages.github.com/versions.json').read)
-
-gem 'github-pages', versions['github-pages']
-```
-</div>
-
-This will ensure that when you run `bundle install`, you
-have the correct version of the `github-pages` gem.
-
-If that fails, simplify it:
-
-<div class="code-block" markdown="1">
-<div markdown="1">
-</div>
-
-```ruby
-source 'https://rubygems.org'
-
-gem 'github-pages'
-```
-</div>
-
-And be sure to run `bundle update` often.
-
-If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on
-[how to install github-pages gem on Windows (x64)](https://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins).
-</div>
-
-<div class="note info">
-  <h5>Installing <code>github-pages</code> gem on Windows</h5>
-  <p>
-    While Windows is not officially supported, it is possible
-    to install <code>github-pages</code> gem on Windows.
-    Special instructions can be found on our
-    <a href="../windows/#installation">Windows-specific docs page</a>.
-  </p>
-</div>
-
 ### User and Organization Pages
 
 User and organization pages live in a special GitHub repository dedicated to
@@ -140,7 +119,7 @@ Please refer to GitHub official documentation on
 to see more detailed examples.
 
 <div class="note warning">
-  <h5>Source Files Must be in the Root Directory</h5>
+  <h5>Source files must be in the root directory</h5>
   <p>
     GitHub Pages <a href="https://help.github.com/articles/troubleshooting-github-pages-build-failures#source-setting">overrides</a>
     the <a href="/docs/configuration/#global-configuration">“Site Source”</a>
@@ -149,12 +128,13 @@ to see more detailed examples.
   </p>
 </div>
 
-<div class="note">
+<div class="note info">
-  <h5>GitHub Pages Documentation, Help, and Support</h5>
+  <h5>Installing the <code>github-pages</code> gem on Windows</h5>
+
   <p>
-    For more information about what you can do with GitHub Pages, as well as for
+    While Windows is not officially supported, it is possible
-    troubleshooting guides, you should check out
+    to install the <code>github-pages</code> gem on Windows.
-    <a href="https://help.github.com/categories/github-pages-basics/">GitHub’s Pages Help section</a>.
+    Special instructions can be found on our
-    If all else fails, you should contact <a href="https://github.com/contact">GitHub Support</a>.
+    <a href="../windows/#installation">Windows-specific docs page</a>.
   </p>
 </div>