1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
---
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 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 front matter as static assets.
So if you only need to push generated HTML, you're good to go without any
further setup.
The [GitHub Pages Documentation](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages)
is comprehensive and includes a [a guide to setting up a GitHub Pages site using
Jekyll](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll).
We recommend following this guide.
This page contains some additional information which may be useful when working
on GitHub Pages sites with Jekyll.
<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://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages">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. 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 the handy [URL filters]({{ '/docs/liquid/filters/' | relative_url }}):
{% raw %}
```liquid
<!-- 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
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 and project pages](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites).
The way to deploy these two types of sites are nearly identical, except for a
few minor details.
### 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 of this branch
structure—the [master branch]({{ site.repository }}) contains the
actual software project for Jekyll, and 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 project pages](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)
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/en/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites">overrides</a>
the <a href="{{ '/docs/configuration/options/' | relative_url }}">“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 info">
<h5>Installing the <code>github-pages</code> gem on Windows</h5>
<p>
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="{{ '/docs/installation/windows/' | relative_url }}">Windows-specific docs page</a>.
</p>
</div>
### Running and Testing Locally
Once the project is configured with the github-pages environment, it's quite hard to switch back and forth with the local settings and the production-level settings. For that we can use certain CLI options to make the workflow hassle-free.
```sh
bundle exec jekyll serve --baseurl=""
```
This will run the jekyll server on your local machine i.e. on `http://localhost:4000`. Refer <a href="{{ '/docs/configuration/options/#serve-command-options' | relative_url }}">server options</a> for available options.
|
