Tuesday, August 20, 2013

Using GitHub Pages To Host Your Website

GitHub Pages

So you want to launch a simple website but don't want to have to go through the dull process of setting up yet another hosting package. There is an easier solution. If you just want to launch a simple static website you can use GitHub Pages to host your site for free.

Lets get started.

Note: This post assumes that you have a GitHub account and some basic knowledge of the version control system Git.

Create Your GitHub Repository

The files that make up your website will need to be stored within a GitHub repository. If you’re creating a website to promote one of your existing GitHub projects you can add the website files to a new branch, otherwise you can just setup a new repo for your site.

Note: If you are not adding your website files to an existing repo make sure that you setup a new repo before continuing.

Now open up terminal (command prompt on Windows) and make sure that you have a copy of your GitHub repo on your computer. Once you got your local copy, move into the project folder using the cd command.

// Retrieve a copy of your GitHub repo.
git clone https://github.com/user/repository.git
// Move into that directory.
cd repository

Note: Make sure that you change the clone URL to the URL of your GitHub repo. This can be found on the main project page.

Creating an Orphan Branch

Now you need to create a new orphan branch within your repo that will hold all of your website files.

This new branch should be called gh-pages.

git checkout --orphan gh-pages

If you already had files in the master branch of your GitHub repo you now need to delete these from the new gh-pages branch. To do this you can use the following command:

git rm -rf .

Adding Your Website Files

Now that your repo has been properly setup it’s time to add all of the HTML, CSS and JavaScript files that make up your website. Once you have added these to your repo you need to commit the changes. To do this you can use the following command.

git commit -a -m "Adding pages"

Note: The -a flag is shorthand for git add.

Pushing Your Changes to GitHub

Okay so you’ve got all your files where they need to be. The only thing left to do now is to push the new gh-pages branch up to GitHub. You do this using the git push command.

git push origin gh-pages

That's it! Your website should now be available at http://username.github.io/repository/.

Using a Custom Domain

The last thing I want to cover in this post is how you can use your own domain name with your new GitHub-hosted website.

First you will need to create a new file in your GitHub repo called CNAME that contains the domain name (or subdomain) that you wish to use. This file should be placed in the gh-pages branch if you are using project-pages (as we have been in this post). If you are using user-pages the file should be placed in the master branch.

Your CNAME file might look like the following:


Next you will need to update the DNS records for your domain name. This is usually done through a control panel provided by your domain registrar.

If you want to use a root domain (such as teamtreehouse.com) for your website you will need to setup a new A record that points to the IP address

If you are using a subdomain (such as blog.teamtreehouse.com) it's best to create a new CNAME record that points to your GitHub user subdomain (**username**.github.io). This is so that the DNS will be automatically adjusted if the servers IP address changes on GitHub.

Note: For information about the difference between CNAME and A records check out this video.

It may take a little while for your DNS changes to take effect. This is usually no more than a few hours. Once the changes have gone through, you should be able to access your new website from your custom domain name.

Final Thoughts

In this post I've showed you how to host pages that you've created yourself but it's worth noting that GitHub also has a tool for automatically generating pages for your projects. You can launch this tool from the project settings page.

GitHub pages does limit you to using static assets (HTML, CSS and JS) for your websites, but you could use something like Jekyll to make it easier to generate these files.

It's not going to meet everyone's needs but if you just want to launch a simple website, GitHub pages is a quick and easy way to get started.