dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: GitHub Pages instructions (#6384) 

Merge pull request 6384
This commit is contained in:
Frank Taillandier 2017-09-25 16:41:58 +02:00 committed by jekyllbot
parent a9b95e58c6
commit e4b456a2ee
1 changed files with 62 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
docs/_docs/github-pages.md
View File

@ -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.
<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... -->
<link href="{{ site.github.url }}/path/to/css.css" rel="stylesheet">
<!-- and for documents/pages whose URLs can change... -->
[{{ page.title }}]("{{ page.url | prepend: site.github.url }}")
<!-- For styles with static names... -->
<link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
<!-- For documents/pages whose URLs can change... -->
[{{ 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">
<h5>GitHub Pages Documentation, Help, and Support</h5>
<div class="note info">
<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
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>.
While Windows is not officially supported, it is possible
to install the <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>