--- 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 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](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.
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.
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 overrides the “Site Source” configuration value, so if you locate your files anywhere other than the root directory, your site may not build correctly.
github-pages
gem on Windows
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.