A guide to using

Github Pages

Are you learning to code and need an easy, free way to host your projects? GitHub pages is your answer. Not only is it an easy hosting solution for websites with HTML, CSS, and JavaScript files, but it also gives you practice using Git, an important but tricky tool. This step-by-step guide gets you up to speed in minutes.

Created by

2

Github has two types of pages. Which type would you like to create?

Use this page if you’re hosting a personal website or an index of your projects, or something that represents you as a whole. You can only have one user page per account. The URL for this page will be http://yourusername.github.io/

Use this page if you’re hosting one project, of which you have many. You can create multiple project pages per account. The URL for this page will be http://yourusername.github.io/projectname/

1

Where are you in your project?

These steps will guide you through initializing a repository and publishing a simple “Hello World” page.

These steps will guide you through pushing your existing project into a repository and publishing it.

2

Github has two types of pages. Which type would you like to create?

Use this page if you’re hosting a personal website or a portfolio of your projects. Note that you can only have one user page attached to your GitHub account. The URL for this page will be http://yourusername.github.io/

Use this page if you’re hosting one project, of which you have many. You can create multiple project pages per account. The URL for this page will be http://yourusername.github.io/projectname/

3

Is your code on Github already?

If you don’t already have a repository on github, we’ll walk you through creating one and pushing the code.

If you do, we’ll walk you through creating a new branch that GitHub pages can access.

{{stepNumbers['create-repo-view']}}

i.

For Repository Name, enter {{repoName}}

{{explain}}

ii.

Make the repository Public

You could make it private, but you’re publishing a website, what are you being so secretive about? Also, making things private costs money.

iii.

Check “Initialize this repository with a README”

Strictly speaking, this is optional, but it makes the next step easier.

iv.

Click Create Repository

If the button is grayed out, make sure the form is filled out completely and no field is selected by your cursor.

{{stepNumbers['terminal-clone-view']}}

Break out the Terminal.

At the command line, create a directory (

mkdir

), and navigate to it (

cd

). You'll later add your code to this directory.

$ mkdir /path/to/source-code

$ cd /path/to/source-code

Download (

clone

) your newly created GitHub repository and go inside it.

If you visit your project’s page on github.com, you should see the link that you need to copy in order to clone. Make sure to select the HTTPS cloning option, and copy the url which should look something like this: https://{{repoURL}}.git

$ git clone https://{{repoURL}}.git

$ cd {{repoName}}

Your newly created repo should only contain the README.md file.

You can tell that this is a git repository because it contains the hidden

.git

directory, which contains the inner workings and configuration files of this repo. To view it, run

ls -a

to list all files.

$ ls

README.md

$ ls -a

. .. .git README.md

{{stepNumbers['branch-view']}}

Add a branch to your {{addBranchText}} repository

At the command line, make sure you are in your local project repo.

$ cd /path/to/repo

Create a new branch called

gh-pages

and check it out.

The branch name

gh-pages

is a special branch that github uses to get files to build and publish from.

$ git checkout -b gh-pages

{{stepNumbers['terminal-put-push-view']}}

Commit and push to GitHub

Create an html page that just says “Hello World”:

For now this will be your home page. Make sure it's located at the base of your repo directory and is named

index.html

so that GitHub knows to display it.

$ echo “Hello, world” > index.html

Add, commit, and push your new page to GitHub!

$ git add index.html

$ git commit index.html -m “My hello world commit”

[{{branchName}} 48d71e6] My hello world commit

1 files changed, 1 insertions(+), 0 deletions(-)

create mode 100644 index.html

$ git push origin {{branchName}}

Counting objects: 4, done.

Delta compression using up to 4 threads.

Compressing objects: 100% (2/2), done.

Writing objects: 100% (3/3), 364 bytes, done.

Total 3 (delta 0), reused 0 (delta 0)

To https://github.com/username/{{repoName}}

￼{{pushPrintout}}

{{stepNumbers['terminal-cp-push-view']}}

Commit and push to GitHub

Copy your files over from wherever they are into this directory.

Make sure your home page is at the base of your repo directory and is named

index.html

so that GitHub knows to display it.

$ cp /path/to/existing/project/* .

Add, commit, and push your new branch to GitHub!

$ git add .

$ git commit -a -m "Adding my existing site."

$ git push origin {{branchName}}

{{stepNumbers['terminal-just-push-gh-pages-view']}}

Push to GitHub

Make sure your home page is at the base of your repo directory and is named

index.html

so that GitHub knows to display it.

Push your new branch to GitHub!

$ git push origin {{branchName}}

Done!

It might take up to 10 minutes, but after that you’ll be able to see your newly created page at