Lesson Tuesday

Note: Make sure not to run $ git init in both your project directory and in a folder within that same project (like your css folder, for example). This causes problems creating a gh-pages branch and pushing it to a remote repo. If you receive an error referencing "submodules", this may be the cause. See a teacher for help fixing this issue.

Note: Make sure not to run $ git init in both your project directory and in a folder within that same project (like your css folder, for example). This causes problems creating a gh-pages branch and pushing it to a remote repo. If you receive an error referencing "submodules", this may be the cause. See a teacher for help fixing this issue.

It's more fun to make web pages when we can show them off to our friends. There are a lot of ways to put our pages online; GitHub Pages is one of the easiest we've found.

First, make sure to have a GitHub account set up. The awesome thing about GitHub pages is that you get one main site per account and as many project pages as you would like. That means that when you are ready to create a portfolio of all of your coding work, you can have a main page all about you and a page for each of your coding projects that you do here at Epicodus or at home!

Project Structure

A quick note about structuring projects before we begin. When we start a new project, it is a good idea to create a folder to hold the HTML file and the css and img folders. So far, we have been using a descriptive name for our HTML file, such as favorite-things.html or my-first-webpage.html. Often, though, you'll want to give the descriptive name for your folder, and name the web page's main HTML file index.html. As we start to add pages to our web site, the index.html file will serve as the home page of our site.

For this lesson, we will be putting our favorite-things.html file on GitHub Pages. Let’s go in the Terminal to our my-first-webpage project folder. Since we want favorite-things.html to be the home page of our site, we need to rename it index.html. GitHub Pages won't recognize it as the main page if we don't.

$ mv favorite-things.html index.html

The mv command in the Terminal moves the content of the favorite-things.html file into a new file called index.html.

Since we have been using Git to track our page's development, let's commit this new change and push it to GitHub (replace the syntax git-pair-commit with git commit if you are working solo).

$ git status
$ git add .
$ git-pair-commit -m "Change name of favorite-things.html file to index.html."
$ git push origin master

Branching

One of the most important features of a version control system like Git is the ability to create a "branch". We will spend more time with branching and merging just a little later, but for now, think of creating a branch like making an exact copy of everything in the project folder. We can experiment with the code - add, delete, move, etc - and it won't change anything in our original "master" branch. In order for GitHub Pages to work, we need to create a branch called gh-pages.

First we will create the new branch and switch into it by running the commands:

$ git branch gh-pages
$ git checkout gh-pages

Pushing Branches to Github

Now that we are in the gh-pages branch, let's push this new branch to GitHub:

$ git push origin gh-pages

Accessing our Web Page

Now our project should be available for viewing at my-github-username.github.io/repository-name. So, for instance, if our GitHub username was sample-epicodus-student, and our repository was named my-first-webpage we would navigate to sample-epicodus-student.github.io/my-first-webpage. Check out the URL that corresponds with your GitHub username and repository name (Note: Repository names are case-sensitive, use the same capitalization pattern as you did when naming the repo!)

You can also set up the GitHub Pages webpage for your project in the browser by going to your project's repository, clicking the branch drop down on the left, typing gh-pages and selecting Create branch: gh-pages. Done!

Updating Github Pages

Note that if you make further changes to your project, you should do so on your master branch rather than on your gh-pages branch. To get back to your master branch, git checkout master. We'll learn in the future about merging branches, but for now the easiest way to update your gh-pages branch is to delete it on Github and then recreate it based on the updated master.

Using GitHub Pages


After you've finished your project, you can create a gh-pages branch either locally or on GitHub to allow your project to be viewable at my-github-username.github.io/repository-name

Create Branch Locally

To create a gh-pages branch locally and then push to GitHub:

$ git branch gh-pages
$ git checkout gh-pages
$ git push [remote nickname] gh-pages

Create Branch on GitHub

To create a gh-pages branch from GitHub:

  1. Click the branch drop down on the left (when viewing the repository on GitHub)
  2. Type gh-pages,
  3. Select Create branch: gh-pages