1. Web Design
  2. GitHub

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.

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.

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.

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

(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.

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:

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:

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!

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.