Introduction to Pages

The GitHub Pages feature allows you to publish content to the web by simply pushing content to one of your GitHub hosted repositories. There are two different kinds of Pages that you can create: User Pages and Project Pages.

User Pages

Let’s say your GitHub username is “alice”. If you create a GitHub repository named, commit a file named index.html into the master branch, and push it to GitHub, then this file will be automatically published to

On the first push, it can take up to ten minutes before the content is available.

Real World Example:

Project Pages

Let’s say your GitHub username is “bob” and you have an existing repository named fancypants. If you create a new root branch named gh-pages in your repository, any content pushed there will be published to

In order to create a new root branch, first ensure that your working directory is clean by committing or stashing any changes. The following operation will lose any uncommitted changes!

$ cd /path/to/fancypants
$ git symbolic-ref HEAD refs/heads/gh-pages
$ rm .git/index
$ git clean -fdx

After running this you’ll have an empty working directory (don’t worry, your main repo is still on the master branch). Now you can create some content in this branch and push it to GitHub. For example:

$ echo "My GitHub Page" > index.html
$ git add .
$ git commit -a -m "First pages commit"
$ git push origin gh-pages

On the first push, it can take up to ten minutes before the content is available.

Real World Example:

Project Page Generator

If you don’t want to go through the steps above to generate your branch, or you simply would like a generic page, you can use our page generator to create your gh-pages branch for you and fill it with a default page.

Page generator

After your page is generated, you can check out the new branch:

$ cd Repos/ampere
$ git fetch origin
remote: Counting objects: 92, done.
remote: Compressing objects: 100% (63/63), done.
remote: Total 68 (delta 41), reused 0 (delta 0)
Unpacking objects: 100% (68/68), done.
 * [new branch]      gh-pages     -> origin/gh-pages
$ git checkout -b gh-pages origin/gh-pages
Branch gh-pages set up to track remote branch refs/remotes/origin/gh-pages.
Switched to a new branch "gh-pages"

Using Jekyll For Complex Layouts

In addition to supporting regular HTML content, GitHub Pages support Jekyll, a simple, blog aware static site generator written by our own Tom Preston-Werner. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers intelligent blog support and other advanced templating features.

Every GitHub Page is run through Jekyll when you push content to your repo. Because a normal HTML site is also a valid Jekyll site, you don’t have to do anything special to keep your standard HTML files unchanged. Jekyll has a thorough README that covers its features and usage.

As of April 7, 2009, you can configure most Jekyll settings via your _config.yml file. Most notably, you can select your permalink style and choose to have your Markdown rendered with RDiscount instead of the default Maruku. The only options we override are as follows:

source: <your pages repo>
destination: <the build dir>
lsi: false
pygments: true

If your Jekyll site is not transforming properly after you push it to GitHub, it’s useful to run the converter locally so you can see any parsing errors. In order to do this, you’ll want to use the same version that we use.

We currently use Jekyll 0.5.7 and run it with the equivalent command:

jekyll --pygments

As of December 27, 2009, you can completely opt-out of Jekyll processing by creating a file named .nojekyll in the root of your pages repo and pushing that to GitHub. This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special dirs and does not copy them to the final destination.

If there’s a feature you wish that Jekyll had, feel free to fork it and send a pull request. We’re happy to accept user contributions.

Real World Example:

Custom Domains

If you or one of the collaborators on your repository have a paid account, GitHub Pages allows you to direct a domain name of your choice at your Page.

Let’s say you own the domain name Furthermore, your GitHub username is “charlie” and you have published a User Page at Now you’d like to load up in your browser and have it show the content from

Start by creating a file named CNAME in the root of your repository. It should contain your domain name like so:

Push this new file up to GitHub. The server will set your pages to be hosted at, and create redirects from and to

Next, you’ll need to visit your domain registrar or DNS host and add a record for your domain name. For a sub-domain like you would simply create a CNAME record pointing at If you are using a top-level domain like, you must use an A record pointing to Do not use a CNAME record with a top-level domain, it can have adverse side effects on other services like email. Many DNS services will let you set a CNAME on a TLD, even though you shouldn’t. Remember that it may take up to a full day for DNS changes to propagate, so be patient.

Real World Example:

Custom 404 Pages

If you provide a 404.html file in the root of your repo, it will be served instead of the default 404 page. Note that Jekyll-generated pages will not work, it must be an html file.

Real World Example: