diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index 2d519f68..5e03201c 100644 --- a/docs/_docs/github-pages.md +++ b/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 -`github.io` domain or on a custom domain name of your choice. GitHub Pages are -powered by Jekyll behind the scenes, so in addition to supporting regular HTML -content, they’re also a great way to host your Jekyll-powered website for free. +organizations, and repositories, that are freely hosted on GitHub's `github.io` +domain or on a custom domain name of your choice. GitHub Pages are powered by +Jekyll behind the scenes, so they're a great way to host your Jekyll-powered +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/). -This guide will teach you what you need to know about Git, GitHub, and Jekyll to create your very own website on GitHub Pages. +Jonathan McGlone](http://jmcglone.com/guides/github-pages/) to get you up and +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. + +
+
GitHub Pages Documentation, Help, and Support
+

+ For more information about what you can do with GitHub Pages, as well as for + troubleshooting guides, you should check out + GitHub’s Pages Help section. + If all else fails, you should contact GitHub Support. +

+
### 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 %} - - - -[{{ 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. -
-
-
- -##### 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`: - -
-
-
- -```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'] -``` -
- -This will ensure that when you run `bundle install`, you -have the correct version of the `github-pages` gem. - -If that fails, simplify it: - -
-
-
- -```ruby -source 'https://rubygems.org' - -gem 'github-pages' -``` -
- -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). -
- -
-
Installing github-pages gem on Windows
-

- While Windows is not officially supported, it is possible - to install github-pages gem on Windows. - Special instructions can be found on our - Windows-specific docs page. -

-
- ### 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.
-
Source Files Must be in the Root Directory
+
Source files must be in the root directory

GitHub Pages overrides the “Site Source” @@ -149,12 +128,13 @@ to see more detailed examples.

-
-
GitHub Pages Documentation, Help, and Support
+
+
Installing the github-pages gem on Windows
+

- For more information about what you can do with GitHub Pages, as well as for - troubleshooting guides, you should check out - GitHub’s Pages Help section. - If all else fails, you should contact GitHub Support. + While Windows is not officially supported, it is possible + to install the github-pages gem on Windows. + Special instructions can be found on our + Windows-specific docs page.