GitHub Pages are public web pages for users,organizations, and repositories, that are freely hosted on GitHub's github.iodomain or on a custom domain name of your choice. GitHub Pages are powered byJekyll behind the scenes, so they're a great way to host your Jekyll-poweredwebsite for free.
Your site is automatically generated by GitHub Pages when you push your sourcefiles. 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 anyfurther setup.
The GitHub Pages Documentationis comprehensive and includes a a guide to setting up a GitHub Pages site usingJekyll.We recommend following this guide.
This page contains some additional information which may be useful when workingon GitHub Pages sites with Jekyll.
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
Want to Submit a Theme? Fork our site on GitHub; Create a new post in the posts directory and fill out the relevant YAML fields; Make a 250x200 thumbnail and drop it in the thumbnails directory. List its filename in the post's markdown file. Test it out, then push your changes up and open a pull request.
Sometimes it's nice to preview your Jekyll site before you push your gh-pagesbranch to GitHub. The subdirectory-like URL structure GitHub uses forProject Pages complicates the proper resolution of URLs. In order to assure yoursite builds properly, use the handy URL filters:
- Although there are plenty of guides introducing Jekyll and Github pages, such as Jonathan's great guide, I would like to record my own preferred way. There are two main steps: Install Jekyll and Jekyll themes; Host on Github.io; Install Jekyll and Jekyll themes. Jekyll is a static-website generator. Install Jekyll using gem install jekyll.
- Clean GitHub Pages theme This is a Jekyll theme for @jasonlong's Cayman theme on GitHub Pages. Cayman is a clean, responsive theme for GitHub Pages. This theme is available as an option if you use the Automatic Page Generator or you can copy the template and styles to use on your own.
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 URLswill 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.The way to deploy these two types of sites are nearly identical, except for afew minor details.
User and Organization Pages
Sometimes it's nice to preview your Jekyll site before you push your gh-pagesbranch to GitHub. The subdirectory-like URL structure GitHub uses forProject Pages complicates the proper resolution of URLs. In order to assure yoursite builds properly, use the handy URL filters:
- Although there are plenty of guides introducing Jekyll and Github pages, such as Jonathan's great guide, I would like to record my own preferred way. There are two main steps: Install Jekyll and Jekyll themes; Host on Github.io; Install Jekyll and Jekyll themes. Jekyll is a static-website generator. Install Jekyll using gem install jekyll.
- Clean GitHub Pages theme This is a Jekyll theme for @jasonlong's Cayman theme on GitHub Pages. Cayman is a clean, responsive theme for GitHub Pages. This theme is available as an option if you use the Automatic Page Generator or you can copy the template and styles to use on your own.
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 URLswill 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.The way to deploy these two types of sites are nearly identical, except for afew minor details.
User and Organization Pages
User and organization pages live in a special GitHub repository dedicated toonly the GitHub Pages files. This repository must be named after the accountname. For example, @mojombo's user page repository has the namemojombo.github.io.
Content from the master branch of your repository will be used to build andpublish the GitHub Pages site, so make sure your Jekyll site is stored there.
Custom domains do not affect repository names
GitHub Pages are initially configured to live under the username.github.io subdomain, which is why repositories must be named this way even if a custom domain is being used.
Github Pages Examples
Project Pages
Unlike user and organization Pages, Project Pages are kept in the samerepository as the project they are for, except that the website content isstored in a specially named gh-pages branch or in a docs folder on themaster branch. The content will be rendered using Jekyll, and the outputwill become available under a subpath of your user pages subdomain, such asusername.github.io/project (unless a custom domain is specified).
The Jekyll project repository itself is a perfect example of this branchstructure—the master branch contains theactual software project for Jekyll, and the Jekyll website that you'relooking at right now is contained in the docsfolder of the same repository.
Please refer to GitHub official documentation onuser, organization and project pagesto see more detailed examples.
Source files must be in the root directory
GitHub Pages overrides the 'Site Source' configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.
Installing the github-pages gem on Windows
Themes For Github Pages
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.
