Applications and Tools

Getting to Know GitHub Pages: Static Project Pages, Fast


Let's talk about GitHub Pages; what they are and how you can use the service in minutes to deploy static pages for free. Let's get started!

What it is

According to GitHub, GitHub Pages are:

... public webpages freely hosted and easily published through our site.

What does this mean to you? It means free, reliable hosting of static content. In general, this was created by GitHub to support open-source projects hosted on GitHub by giving them a place to offer documentation, demos, or any other given interactive experience to complement the code in the repository.


However, GitHub pages can be used for a variety of projects, and already supports Jekyll (a powerful, Ruby-based static site generator). So, let's learn how to use it!

Before We Get Started

You will need to signup for a GitHub account before you can get started with GitHub pages. To receive the most benefit from GitHub, it is highly recommended that you set up your SSH keys. Basically, the instructions at this link let you securely connect your computer with your GitHub account and all of your repositories on GitHub. Once you have created a GitHub account and registered your keys, you can easily download the GitHub app for Mac or GitHub for Windows, both officially supported by GitHub.

Back up - What in the World is GitHub?

GitHub is a place for people to store their code. Git is a powerful version-control system that allows developers to track changes made to code in increments, called commits, and track different paths of a particular project by using branches.


There are a lot of features of Git, and even more power is locked up in GitHub, but for now we will stay focused on GitHub Pages. If you'd like to learn more about GitHub, check out Git for Designers, as well as Git & GitHub: A Beginner's Guide, which include some more information about SSH keys, as well as some basic Git functionality that is beyond the scope of this article.

Different Ways to Use GitHub Pages

There are a variety of ways GitHub Pages can be used. We'll start with one of the fastest ways.

GitHub's Automatic Page Generator

The Automatic Page Generator allows users to create their page using Markdown, a human-readable markup language designed to help content creators easily produce documents with a consistent set of markup guidelines.

So how do you use the Automatic Page Generator? First, you'll want to create a repository. If you want the repo to point to, create a repo matching that name. For instance, my personal repo is named To access the static site generator, go to that repo's settings (accessible at a url that follows the format This will show an editor, which is powered by a Markdown rich text editor. You can automatically copy in the standard file, or you can edit your content to your choosing. Furthermore, the automatic generator also has a space for Google Analytics tracking.

Once you have added all relevant content, you can advance to the layout selector. With multiple themes to select from, this is a great option for immediately giving users a no-effort, DRY landing page based on your Readme file that simply requires you to keep your documentation up to date (something you should already be doing). You can also pull these pages down from their origin, modify them locally and then push them back up.

If you want to use the GitHub app to control your GitHub repository, here's how you might do it.

First, you'll want to install the app from or, and follow the simple setup instructions.


Then, choose a repository you want to clone to your computer by selecting your GitHub username on the left and clicking Clone to Computer.


Next, configure the location and name you'd like to clone the repository as.


Then, choose the branches tab on the left, and select the gh-pages branch that was created by the generator. You can then make your edits locally in the location you specified previously.

Once you are ready to push some changes to be live, go to the changes tab and create a commit with the form at the top left.


Finally, select the branches tab and click publish to the right of the gh-pages branch. This will push all of your committed changes to GitHub.


If you want to use the command line to control your GitHub repository, here's how you might do it.

git clone
git checkout gh-pages

If you generated a user page (instead of a single project), the master branch is the GitHub pages branch. Simply clone your user project to edit it locally.

git clone
git checkout master # this should be already checked out by default

However, the automatic generator may not be the solution to your problem. Perhaps you have already built your site statically, and are simply looking to deploy it somewhere.

Build it out Manually

This second option is as simple as it sounds. In order to make GitHub pages work with arbitrary local content, first create the repository on GitHub.

If you've decided to use the GitHub app, here's how you'd create your own manual pages.

Select the My Repositories folder tab, and then click the arrow on the repository you want to create GitHub Pages with. If you currently don't have any repositories to kick things off with, you can create one from within the app.


If you are creating GitHub Pages using, the master branch is the pages branch, so you can go ahead and open the project in a local folder, skipping creation of the gh-pages branch. If you are creating GitHub Pages for a project, you'll want to create a new branch called gh-pages; click on the button on the right side of the repository, then simply click the + button on the right side of the current branch.


This will allow you to enter the new branch name.


By default, the new branch will have all of your current project files, so you'll want to remove all of the files in the project while the gh-pages branch is selected. (To be sure, make sure the "current branch" indicator shows that you are on the gh-pages branch, unless you are creating pages for


Then, you can create a static site directly in your project folder.

Once you have created the static site in the project folder, you will return to the GitHub app and go to the changes tab on the left. This will show all of the changes you have made, including the deletion of the original files. Create a commit by filling out the form at the top left. Once you have done this, you can go back to the branches tab and publish the gh-pages branch (or the master branch, if you are creating pages for This is the step that pushes your code to GitHub and initiates the static site on the server.

You can also easily clone the repository through the command line by selecting the URL at the top of the project page and running the following command.

git clone

Next, you will need to create a new branch called gh-pages; this branch needs to be completely empty, also. Run these commands:

git checkout --orphan gh-pages
git rm -rf .
git commit -am "initial pages commit"

(For more information, check out the official documentation).

This will pull down the project to a folder called projectname (whatever your project is) in your current working directory, and will also automatically have GitHub as the remote origin. Basically this means you can create files and make changes, then follow the next few commands to track those files and changes, and push them to GitHub.

git status # retrieves and echos the current status of the repository; this will show new files and untracked changes
git add . # this adds all new files created
git commit -am "Here is my initial commit" # this creates a commit on your current branch (by default, the master branch)
git push origin gh-pages #this pushes the gh-pages branch back to GitHub.

This process will be repeated throughout all iterations of your site as you make changes. This works great, but what if you want to host a static blog? Arguably the most popular static blogging platform, Jekyll, is supported by GitHub pages by default. (Jekyll was built by a team member at GitHub.)

Use Jekyll with GitHub Pages

To Use Jekyll with GitHub Pages, you will first need to create a Jekyll site locally. You can compile locally, or you can allow GitHub to compile for you. To get started, you can follow this guide about Octopress, a framework that abstracts some of the basic functions of Jekyll.

Alternatively, you can create a raw Jekyll site. First, you will need to install the jekyll gem. Generally, this means running the following command:

gem install jekyll

If you have RubyGems installed, this should pull the latest stabile release.

Take a look at the usage guide, as well as this guide on NetTuts. You will need to create the basic file structure before Jekyll can generate a site. To get up and running quickly, take a look at Daniel McGraw's Jekyll-Base, which defines the file structure necessary for Jekyll to generate a site. I've also taken a few moments to create a reusable script called jekyll_structure. Follow the installation instructions; if it doesn't work for you, simply manually create the following structure.

|-- .gitignore
|-- _config.yml
|-- _layouts
| |-- layout.html
| `-- post.html
|-- _posts
| `--
`-- index.html

The primary configuration for Jekyll will be put into the _config.yml file. _layouts will hold the layouts that will be used upon generation.

Once you have created posts and pages, and subsequently edited them, you can simply add them to your git repository and commit them, as previously explained:

git add .
git commit -am "Added a new post"
git push origin gh-pages # or git push origin master for pages

Note: it is much easier to use frameworks like Octopress or Jekyll Bootstrap to auto-generate posts and pages for Jekyll, with commands resembling rake new_post["Post Name Goes Here"] instead of manually creating your post or page files.

Other Important Things of Note

It's important to remember that repositories that are set as private on GitHub will create public pages. GitHub created this feature for projects to easily publish documentation; this is centered around the idea of openness. Static sites hosted on GitHub won't be hidden from anyone anytime soon.

Don't limit yourself to the design or structure that is predefined in the auto-generated pages GitHub provides. These are easily editable by simply pulling the repository down to your local machine, making changes, and submitting them.

The more you learn about Git and GitHub, the more comfortable you will be with GitHub Pages. Take a look at this post on Treehouse, as well as this Tutsplus tutorial from Jeffrey Way about GitHub for Designers.

If you'd like to redirect your own domain to a GitHub Pages domain, check out this guide on GitHub's help page to get started. Who knows - maybe you can get rid of your personal hosting provider and go all static!


GitHub Pages is extremely convenient to use, especially when paired with other tools like Jekyll. Learning the tools that GitHub Pages depends on will help you become a better and more valuable front-end developer and designer, and it's a great way to showcase your projects. Furthermore, GitHub provides this as a free service to everyone, so the cost to get started is limited to the value of the time you spend learning. What are you waiting for? Dive in!

Related Posts
  • Code
    Web Development
    Easily Deploy Redis Backed Web Apps With DockerDocker wide retina preview
    Learn how to setup and deploy a Redis powered Python web app using Docker.Read More…
  • Code
    Setting Up a Local Mirror for Composer Packages With SatisComposer retina preview
    Installing all your PHP libraries with Composer is a great way to save time. But larger projects automatically tested and run at each commit to your software version control (SVC) system will take a long time to install all the required packages from the Internet. You want to run your tests as soon as possible through your continuous integration (CI) system so that you have fast feedback and quick reactions on failure. In this tutorial we will set up a local mirror to proxy all your packages required in your project's composer.json file. This will make our CI work much faster, install the packages over the local network or even hosted on the same machine, and make sure we have the specific versions of the packages always available.Read More…
  • Code
    Tools & Tips
    Coding in the CloudCoding in cloud retina preview
    The Internet has allowed us to work anywhere we want, giving us tremendous flexibility in choosing where we'd like to plant ourselves to build the next great app. Not being tied to an office desk has been a blessing to many who cherish the ability to work in varying environments and draw inspiration from their surroundings. But for the most part, we've needed to have a full-blown development machine to make this happen. What if we could leverage the cloud as a development environment itself, freeing us up to choose from a variety of devices to accomplish the same thing. That's what we'll explore in this article.Read More…
  • Code
    Tools & Tips
    Travis-CI: What, Why, HowTravis retina logo
    Travis CI makes working in a team for a software project easier with automated builds. These builds are triggered automatically when each developer checks in their code to the repository. In this article, we will go through how we can integrate Travis CI easily with our project, which is hosted on Github. With automation, notification and testing in place, we can focus on our coding and creating, while Travis CI does the hard work of continuous integration!Read More…
  • Game Development
    Git and GitHub for Game DevelopersGit and github for game developers 400px
    "I'm sure Git is great, but it looks complicated - I'll stick with my current workflow" is like saying "I'm sure IDEs like FlashDevelop and Sublime Text are great, but they look complicated - I'll stick with Notepad". Yeah, sure, there's a bit of a learning curve, and you can live without it, but it's foolish to. In this article, I'll explain why Git (and GitHub) is so great, and show you how to get started quickly and easily.Read More…
  • Code
    Tools & Tips
    How to Collaborate On GitHubGithub collab retina preview
    If you don't already know, GitHub is an incredibly effective way to collaborate on development projects. Providing a place for anyone with an internet connection to have an avenue where they can share code with the world for free (not to mention the robust supporting tools for source inspection and easy viewing of commit histories). GitHub has been adopted by many large open-source projects as their primary home for collaboration and contribution. But how do you join in and contribute to a project? Sure, you know how to use Git to track changes to files and push those files to a server. But there are major benefits to getting involved in larger open-source projects, and GitHub is arguably the best place to start. Today, we will discuss a few rules of the road for collaborating on open source projects, and give you the knowledge and intuition you will need to get involved.Read More…