164 lines
6.1 KiB
Markdown
164 lines
6.1 KiB
Markdown
---
|
||
layout: docs
|
||
title: GitHub Pages
|
||
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.
|
||
|
||
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.
|
||
|
||
### 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 URL's.
|
||
|
||
```html
|
||
{% raw %}
|
||
<!-- Useful for styles with static names... -->
|
||
<link href="{{ site.github.url }}/path/to/css.css" rel="stylesheet">
|
||
<!-- and for documents/pages whose URL's can change... -->
|
||
[{{ page.title }}]("{{ page.url | prepend: site.github.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
|
||
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.
|
||
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
|
||
only the GitHub Pages files. This repository must be named after the account
|
||
name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.io) has the name
|
||
`mojombo.github.io`.
|
||
|
||
Content from the `master` branch of your repository will be used to build and
|
||
publish the GitHub Pages site, so make sure your Jekyll site is stored there.
|
||
|
||
<div class="note info">
|
||
<h5>Custom domains do not affect repository names</h5>
|
||
<p>
|
||
GitHub Pages are initially configured to live under the
|
||
<code>username.github.io</code> subdomain, which is why repositories must
|
||
be named this way <strong>even if a custom domain is being used</strong>.
|
||
</p>
|
||
</div>
|
||
|
||
### Project Pages
|
||
|
||
Unlike user and organization Pages, Project Pages are kept in the same
|
||
repository as the project they are for, except that the website content is
|
||
stored in a specially named `gh-pages` branch or in a `docs` folder on the
|
||
`master` branch. The content will be rendered using Jekyll, and the output
|
||
will become available under a subpath of your user pages subdomain, such as
|
||
`username.github.io/project` (unless a custom domain is specified).
|
||
|
||
The Jekyll project repository itself is a perfect example: the
|
||
[master branch]({{ site.repository }}) contains the actual software project
|
||
for Jekyll, however the Jekyll website (that you’re looking at right now) is
|
||
contained in the [docs folder]({{ site.repository }}/tree/master/docs) of the
|
||
same repository.
|
||
|
||
Please refer to GitHub official documentation on
|
||
[user, organization and projets pages](https://help.github.com/articles/user-organization-and-project-pages/)
|
||
to see more detailed examples.
|
||
|
||
<div class="note warning">
|
||
<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>
|
||
configuration value, so if you locate your files anywhere other than the
|
||
root directory, your site may not build correctly.
|
||
</p>
|
||
</div>
|
||
|
||
<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>
|